On this page
Leases
A Lease is one isolated machine of a shape, region, and image for a bounded time.
A Lease is one isolated machine of a shape, region, and image for a bounded time. It is granted immediately from a warm or cold machine, or refused with a typed reason; its end destroys the machine. Sandboxes is its only writer. Put the caller's own correlation (agent id, work id) in meta.labels; List filters on them.
Service Sylphx Sandboxes · Resource type sandboxes.sylphx.com/Lease · Name pattern orgs/{org}/projects/{project}/envs/{env}/leases/{lease} · Shape spec_status
Fields
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/leases/{lease}. |
uid | string | sbx_<cell><ulid>; never reused. Output only. |
meta | ResourceMeta | Resource metadata. |
spec | LeaseSpec | Desired state; omit it, or send it empty, for the zero-config lease: the platform resolves and records the shape and ttl (see LeaseSpec). |
status | LeaseStatus | Observed state. Output only. |
Methods
Every method of the collection, in the registry's order, with the scope it needs. The full request, response and examples are one link away.
| Method | Call | What it does |
|---|---|---|
GET | get | Gets a lease. |
GET | list | Lists leases in a environment. Filter on meta.labels (for example labels.agent = "a_123"), status.state, and spec.kind. |
POST | create | Creates a lease: granted now and returned READY (or GRANTED when wait_ready is false), or refused with a typed error. There is no queue. |
POST | renew | Extends expire_time, never past the shape's longest lease. Does not change the generation. |
POST | release | Ends a lease with END_REASON_RELEASED; the machine is destroyed and never leased again, and attached volumes are detached. |
POST | pause | Pauses a lease: its disk is kept and its machine destroyed; the generation increases. Process memory is not kept. |
POST | resume | Resumes a paused lease on a machine granted now, or refuses it; the generation increases. |
POST | set_network | Replaces a running lease's outbound policy. The generation does not change; the new policy applies before the call returns. |
POST | mint_token | Mints a lease token for the data plane, bound to the current generation. Hand it to a process that must not hold the Access key. |
POST | exec | 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. |
POST | cancel_exec | Requests cancellation of the existing execution key. This acknowledgement means the request was recorded, not that the process has stopped. Observe the exact original ExecLease request for its confirmed terminal result. An already completed result wins; an unknown outcome remains unknown. |
POST | read_file | Reads one file from the lease, at most 16 MiB; larger files use the guest's /files. |
POST | write_file | Writes one file in the lease, at most 16 MiB, creating parent directories. |
POST | list_files | Lists one directory in the lease. |
POST | remove_file | Removes one file or directory tree in the lease. |
POST | open_port | Exposes a guest port. |
POST | close_port | Stops exposing a guest port. |
POST | act | Performs computer actions on a DESKTOP, BROWSER, or ANDROID lease, in order, and returns each action's result and, when screenshot is set, the screenshot taken after the last action. The actions are the Anthropic computer tool's and OpenAI computer use's, one-to-one. Refused CONTROL_HELD_BY_HUMAN while a human holds control. |
POST | open_stream | Opens a read-only live view of a lease's display: a short-lived viewer token bound to the lease and its generation, an embeddable URL, and the WebRTC signaling endpoint with ICE servers. Input needs control (AcquireLeaseControl). |
POST | acquire_control | Takes exclusive input control of a lease's display. A HUMAN acquire preempts an AGENT holder and returns a controller stream; an AGENT acquire is refused CONTROL_HELD_BY_HUMAN while a human holds control. Control lapses at ttl, which the platform caps at 30 minutes. |
POST | release_control | Releases control held under epoch; its controller tokens stop working. |
GET | get_control | Gets who holds control of a lease's display. |
POST | install_app | Installs an Android app (APK) on an ANDROID lease. |
get
Gets a lease.
GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease · scope sandboxes:read · effect read · Request, response and examples
list
Lists leases in a environment. Filter on meta.labels (for example labels.agent = "a_123"), status.state, and spec.kind.
GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases · scope sandboxes:read · effect read · paginated · Request, response and examples
create
Creates a lease: granted now and returned READY (or GRANTED when wait_ready is false), or refused with a typed error. There is no queue.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases · scope sandboxes:write · effect write · Request, response and examples
renew
Extends expire_time, never past the shape's longest lease. Does not change the generation.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:renew · scope sandboxes:write · effect write · validate_only · Request, response and examples
release
Ends a lease with END_REASON_RELEASED; the machine is destroyed and never leased again, and attached volumes are detached.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:release · scope sandboxes:write · effect destructive · validate_only · Request, response and examples
pause
Pauses a lease: its disk is kept and its machine destroyed; the generation increases. Process memory is not kept.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:pause · scope sandboxes:write · effect write · validate_only · Request, response and examples
resume
Resumes a paused lease on a machine granted now, or refuses it; the generation increases.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:resume · scope sandboxes:write · effect write · validate_only · Request, response and examples
set_network
Replaces a running lease's outbound policy. The generation does not change; the new policy applies before the call returns.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:setNetwork · scope sandboxes:write · effect write · Request, response and examples
mint_token
Mints a lease token for the data plane, bound to the current generation. Hand it to a process that must not hold the Access key.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:mintToken · scope sandboxes:exec · effect write · Request, response and examples
exec
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.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:exec · scope sandboxes:exec · effect write · Request, response and examples
cancel_exec
Requests cancellation of the existing execution key. This acknowledgement means the request was recorded, not that the process has stopped. Observe the exact original ExecLease request for its confirmed terminal result. An already completed result wins; an unknown outcome remains unknown.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:cancelExec · scope sandboxes:exec · effect write · Request, response and examples
read_file
Reads one file from the lease, at most 16 MiB; larger files use the guest's /files.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:readFile · scope sandboxes:exec · effect read · Request, response and examples
write_file
Writes one file in the lease, at most 16 MiB, creating parent directories.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:writeFile · scope sandboxes:exec · effect write · Request, response and examples
list_files
Lists one directory in the lease.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:listFiles · scope sandboxes:exec · effect read · Request, response and examples
remove_file
Removes one file or directory tree in the lease.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:removeFile · scope sandboxes:exec · effect destructive · Request, response and examples
open_port
Exposes a guest port.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:openPort · scope sandboxes:exec · effect write · Request, response and examples
close_port
Stops exposing a guest port.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:closePort · scope sandboxes:exec · effect write · Request, response and examples
act
Performs computer actions on a DESKTOP, BROWSER, or ANDROID lease, in order, and returns each action's result and, when screenshot is set, the screenshot taken after the last action. The actions are the Anthropic computer tool's and OpenAI computer use's, one-to-one. Refused CONTROL_HELD_BY_HUMAN while a human holds control.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:act · scope sandboxes:exec · effect write · Request, response and examples
open_stream
Opens a read-only live view of a lease's display: a short-lived viewer token bound to the lease and its generation, an embeddable URL, and the WebRTC signaling endpoint with ICE servers. Input needs control (AcquireLeaseControl).
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:openStream · scope sandboxes:exec · effect write · Request, response and examples
acquire_control
Takes exclusive input control of a lease's display. A HUMAN acquire preempts an AGENT holder and returns a controller stream; an AGENT acquire is refused CONTROL_HELD_BY_HUMAN while a human holds control. Control lapses at ttl, which the platform caps at 30 minutes.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:acquireControl · scope sandboxes:exec · effect write · Request, response and examples
release_control
Releases control held under epoch; its controller tokens stop working.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:releaseControl · scope sandboxes:exec · effect write · Request, response and examples
get_control
Gets who holds control of a lease's display.
GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:getControl · scope sandboxes:read · effect read · Request, response and examples
install_app
Installs an Android app (APK) on an ANDROID lease.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:installApp · scope sandboxes:exec · effect write · Request, response and examples