Exec a lease
Dispatches one command at most once per lease and execution key.
Dispatches one command at most once per lease and execution key. Each HTTP response waits at most 20 seconds: repeat the exact request and key after IDEMPOTENCY_IN_PROGRESS, honoring Retry-After, until the recorded result or a terminal error arrives. Pending observations do not consume the client's transient-error retry budget. Disconnect only stops waiting. Results (capped at 1 MiB per stream) remain replayable after lease expiry. An unknown outcome is never dispatched again. Interactive processes use the guest protocol at status.endpoints.guest_uri.
- Path
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:exec - Scope
sandboxes:exec - Effect
write— a successful call changes state. - Collection leases
Request
| Field | Type | What it is |
|---|---|---|
name | string | The name of the lease. Required. |
command | string[] | The program and its arguments. Use ["bash", "-lc", "…"] for a shell. Required. |
working_directory | string | The working directory; default the user's home. |
env | map<string, string> | Extra environment variables. |
stdin | bytes | Bytes written to standard input. |
timeout | duration | Kill the process after this long; default 60 seconds, at most 30 minutes, and never past the lease's expire_time. |
user | string | The guest user; default user. root is allowed: the whole machine belongs to the lessee. |
idempotency_key | string | Stable execution identity, 1-255 printable ASCII characters. Required here or in the Idempotency-Key header (this field takes precedence). Persist it with the complete request before sending; use the same key and request to recover after any disconnect or caller restart. The first call claims the key before the command starts; a later call with the same key and request returns the recorded result (also after the lease ended), IDEMPOTENCY_IN_PROGRESS while the first still runs (the command continues after the call returns), and EXEC_OUTCOME_UNKNOWN when the outcome was lost after dispatch. The same key with another request is IDEMPOTENCY_KEY_REUSED. A refusal before the command started releases the key. |
Response
| Field | Type | What it is |
|---|---|---|
exit_code | int32 | The confirmed process exit code (including a signal exit, such as 137). |
stdout | bytes | Standard output. |
stderr | bytes | Standard error. |
truncated | bool | Whether either stream exceeded the cap. |
timed_out | bool | Whether the process was killed at timeout. |
cancelled | bool | Whether an explicit cancellation was confirmed by process termination. A cancellation acknowledgement alone never sets this field. |
idempotency_key | string | The stable key used to dispatch this command. |
execution_id | string | The one dispatch identity, unchanged on every terminal replay. |
Errors
UNAUTHENTICATED— No valid key or token was presented.PERMISSION_DENIED— The key lacks the method's permission.RESOURCE_NOT_FOUND— The named Resource does not exist or is not visible.INVALID_STATE— The Resource is in a state that forbids the call.DEVICE_LOST— The Android device is no longer online. The lease retains its machine and files until release or expiry. No new device action or execution was dispatched.STALE_GENERATION— The call named a lease generation or control epoch that is no longer current.IDEMPOTENCY_KEY_REUSED— An Idempotency-Key was reused with another body.IDEMPOTENCY_IN_PROGRESS— The first call with this Idempotency-Key is still running.EXEC_OUTCOME_UNKNOWN— A keyed command was dispatched to the guest but its outcome was lost (the dispatcher, the stream, or the lease ended before the result was recorded). The key never runs again; the command may or may not have taken effect. Not retryable with the same key.
Every error arrives in the body Errors describes.
Examples
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:exec" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":["…"]}'