Automation API Overview

ZestSSH Pro includes an automation API that allows external apps to trigger SSH commands on your saved connections without opening ZestSSH’s UI. This enables integration with Tasker (Android), Shortcuts (iOS), webhooks, and other automation tools.

Architecture

The automation system has two entry points:

1. URL Scheme (zestssh://) --- Works on all platforms. External apps open a URL, and ZestSSH intercepts it.
2. Android Intents --- Android-specific. External apps send a targeted intent to ZestSSH’s service component.

Both entry points feed into the same internal automation engine:

External App
    |
    v
[URL Scheme / Android Intent]
    |
    v
[Deep Link Service] --- validates, parses, rate-limits
    |
    v
[Automation Provider] --- checks Pro status, API key, enabled flag
    |
    v
[Automation Service] --- headless SSH: connect, execute, disconnect
    |
    v
[Result] --- returned to caller + logged to automation history

API Key Model

Every automation request must include a valid API key. Keys are:

• 48 characters of alphanumeric characters, generated by a cryptographically secure random number generator (CSPRNG backed by the OS’s /dev/urandom equivalent).
• Providing approximately 285 bits of entropy.
• Stored in the platform’s secure keychain (Android Keystore, iOS Keychain, desktop equivalents).
• Validated using constant-time comparison (SHA-256 hash comparison) to prevent timing attacks.
• Tracked with last used timestamps and optional expiration dates.

Key Lifecycle

1. Create: Settings > Automation > Manage API Keys > Create Key. Assign a label and optional expiration.
2. Use: Pass the key in each automation request.
3. Rotate: Create a new key, update your automation tasks, then delete the old key.
4. Revoke: Delete a key to immediately invalidate it.

You can create multiple keys (e.g. one per Tasker profile, one per Shortcuts workflow) and revoke them independently.

Rate Limiting

To protect against brute-force API key guessing:

• After 5 consecutive failed API key validations, ZestSSH locks out all automation requests for 60 seconds.
• The lockout counter and timestamp are persisted to secure storage, so restarting the app does not bypass the lockout.
• Successful validation resets the failure counter.
• Expired keys are treated as invalid and contribute to the failure counter.

Requirements

• ZestSSH Pro subscription --- Automation is a Pro-only feature. Free-tier users receive a clear error message when automation is attempted.
• Automation enabled --- The user must toggle automation on in Settings > Automation. It can be disabled to block all external command execution.
• Valid API key --- Every request must include a key that passes validation.

Execution Model

The automation engine uses headless SSH execution:

1. Connects to the target server using the saved connection’s credentials.
2. Runs the command via SSHClient.execute() (no PTY allocated).
3. Captures stdout and stderr.
4. Returns the exit code, output, elapsed time, and success/failure status.
5. Disconnects.

This is designed for non-interactive commands. Commands that require a PTY (like top or interactive editors) will not work correctly in automation mode.

Timeout

Each command has a configurable timeout (default: 30 seconds, maximum: configurable per request). The timeout covers the entire lifecycle: TCP connect, SSH authentication, command execution, and output collection.

Host Key Handling

In automation mode, new host keys are automatically trusted (TOFU --- Trust On First Use). Changed host keys are rejected to protect against man-in-the-middle attacks. There is no interactive prompt in headless mode.

Connection Resolution

The connection parameter in automation requests is resolved flexibly:

1. Exact ID match (UUID) --- highest priority.
2. Exact label match (case-insensitive).
3. Partial label match (first hit, case-insensitive).

This means connection=prod will match a connection labeled “Production Server” if no exact match exists.

Automation History

Every automation execution is logged to an on-device database with:

• Timestamp
• Action type (execute, snippet, batch, workflow, connect)
• Connection ID
• Command
• stdout, stderr
• Exit code
• Success/failure status
• Elapsed time in milliseconds

The log retains up to 500 entries (oldest are trimmed automatically). View it at Settings > Automation > Log.

Available Actions

Action	Description	Reference
execute	Run a command on a single connection	Endpoints
snippet	Run a saved snippet by name with optional variables	Endpoints
batch	Run a command across multiple connections	Endpoints
workflow	Run a multi-step workflow by name or ID	Endpoints
connect	Verify connectivity to a connection	Endpoints