Reference

Leases

A Lease is one isolated machine of a shape, region, and image for a bounded time.

Checked 2026-09-28

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. Required.
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	Runs one command in the lease to completion and returns its output, capped at 1 MiB per stream. Long-running or interactive processes use the guest protocol at status.endpoints.guest_uri.
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

Runs one command in the lease to completion and returns its output, capped at 1 MiB per stream. Long-running or 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

#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