Exec a lease

Runs one command in the lease to completion and returns its output, capped at 1 MiB per stream.

Checked 2026-09-28

Runs one command in the lease to completion and returns its output, capped at 1 MiB per stream. With idempotency_key the command is dispatched at most once per lease and key, and its recorded result is returned again, also after the lease ended. Long-running or 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`	Dispatches the command at most once per lease and key, 1-255 printable ASCII characters. 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 exit code; -1 when killed.
`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`.

#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.
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":["…"]}'

Was this page helpful?

Tell us what is missing, wrong, or unclear — this opens a real inbox.

Send feedback

Platform links