MacroDroid Integration
MacroDroid is a popular Android automation app that can trigger ZestSSH actions using the zestssh:// URL scheme. Unlike Tasker, MacroDroid uses the “Open Website” action to launch URLs, making setup straightforward.
How It Works
Section titled “How It Works”MacroDroid opens a zestssh:// URL, which Android routes to ZestSSH. The app parses the URL parameters, validates the API key, connects to the target server, runs the command, and returns the result. All of this happens in the background — ZestSSH opens briefly to process the request and can return to the background afterward.
Setup Steps
Section titled “Setup Steps”1. Generate an API Key
Section titled “1. Generate an API Key”Before creating your MacroDroid macro, generate an API key in ZestSSH:
- Open ZestSSH and go to Settings > Automation > API Keys.
- Tap Generate New Key.
- Enter a label (e.g., “MacroDroid”).
- Optionally set an expiration date.
- Copy the generated key — you will need it for the URL.
2. Create a MacroDroid Macro
Section titled “2. Create a MacroDroid Macro”- Open MacroDroid and tap Add Macro.
- Add Trigger: choose any trigger you want (time, event, NFC tag, widget button, etc.).
- Add Action: select Applications > Open Website / URL.
- Paste your
zestssh://URL in the URL field (see URL formats below). - Important: uncheck “Use Built-in Browser”. This ensures the URL is handled by ZestSSH rather than opening in a web view.
- Save the macro.
3. Test the Macro
Section titled “3. Test the Macro”Tap the play button on the macro to test it. ZestSSH should briefly appear, execute the command, and the result will be logged in ZestSSH’s automation history.
URL Formats
Section titled “URL Formats”Execute a Command
Section titled “Execute a Command”zestssh://execute?connection=LABEL&command=COMMAND&key=API_KEYOptional parameters: timeout (seconds), grep (filter pattern), head (first N lines), tail (last N lines), callback (webhook URL).
Run a Snippet
Section titled “Run a Snippet”zestssh://snippet?connection=LABEL&name=SNIPPET_NAME&key=API_KEYOptional: var_VARNAME=value for snippet variables.
Batch Execute
Section titled “Batch Execute”zestssh://batch?connections=LABEL1,LABEL2,LABEL3&command=COMMAND&key=API_KEYOptional: parallel=true (default) or parallel=false, timeout, grep, head, tail, callback.
Connect (Verify)
Section titled “Connect (Verify)”zestssh://connect?host=LABEL&key=API_KEYRun a Workflow
Section titled “Run a Workflow”zestssh://workflow?name=WORKFLOW_NAME&key=API_KEYOr by ID: zestssh://workflow?id=WORKFLOW_UUID&key=API_KEY.
Examples
Section titled “Examples”Morning server health check
Section titled “Morning server health check”Trigger: Time trigger, every day at 7:00 AM. Action: Open Website / URL:
zestssh://execute?connection=production-web&command=uptime%20%26%26%20df%20-h%20%2F&key=YOUR_API_KEY(URL-encoded: uptime && df -h /)
Restart a Docker container from a widget
Section titled “Restart a Docker container from a widget”Trigger: MacroDroid widget button tap. Action: Open Website / URL:
zestssh://snippet?connection=docker-host&name=Restart%20Container&var_DOCKER=nginx-proxy&key=YOUR_API_KEYCheck disk usage on multiple servers
Section titled “Check disk usage on multiple servers”Trigger: Any trigger of your choice. Action: Open Website / URL:
zestssh://batch?connections=web1,web2,db1&command=df%20-h%20%2F¶llel=true&key=YOUR_API_KEYDeploy with webhook notification
Section titled “Deploy with webhook notification”Trigger: NFC tag scan. Action: Open Website / URL:
zestssh://execute?connection=staging&command=cd%20%2Fapp%20%26%26%20git%20pull&callback=https%3A%2F%2Fhooks.slack.com%2Fservices%2FXXX&key=YOUR_API_KEYURL Encoding
Section titled “URL Encoding”Special characters in commands must be URL-encoded. Common encodings:
| Character | Encoded |
|---|---|
| space | %20 |
/ | %2F |
& | %26 |
= | %3D |
| | %7C |
MacroDroid handles some encoding automatically, but if your command includes special characters and the macro fails, try encoding them manually.
Using the Automation Wizard
Section titled “Using the Automation Wizard”The fastest way to get a correctly formatted URL is to use ZestSSH’s built-in Automation Wizard:
- Go to Settings > Automation > Automation Wizard.
- Walk through the steps: pick action, connection, command, filters.
- On the result screen, the wizard shows a dedicated MacroDroid card with step-by-step instructions and a ready-to-copy URL.
- Use MacroDroid’s Constraint feature to limit when macros can fire (e.g., only when on Wi-Fi).
- Combine with MacroDroid’s notification actions to display the automation result.
- Keep API key URLs private — anyone with the URL and key can execute commands on your servers.
- For complex multi-step operations, use a workflow URL instead of chaining multiple macros.