Skip to content
Console
On this page

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

FieldTypeWhat it is
namestringThe name of the lease. Required.
commandstring[]The program and its arguments. Use ["bash", "-lc", "…"] for a shell. Required.
working_directorystringThe working directory; default the user's home.
envmap<string, string>Extra environment variables.
stdinbytesBytes written to standard input.
timeoutdurationKill the process after this long; default 60 seconds, at most 30 minutes, and never past the lease's expire_time.
userstringThe guest user; default user. root is allowed: the whole machine belongs to the lessee.
idempotency_keystringStable 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

FieldTypeWhat it is
exit_codeint32The confirmed process exit code (including a signal exit, such as 137).
stdoutbytesStandard output.
stderrbytesStandard error.
truncatedboolWhether either stream exceeded the cap.
timed_outboolWhether the process was killed at timeout.
cancelledboolWhether an explicit cancellation was confirmed by process termination. A cancellation acknowledgement alone never sets this field.
idempotency_keystringThe stable key used to dispatch this command.
execution_idstringThe 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":["…"]}'