---
# @generated by sylphx-gen 0.1.0 from contracts@e145cc7cf1bc9605f2b27439e5e17ed76a1a2fd7e7021906a013f7565e4a0cd5. Do not edit.
title: "Leases"
description: "The `leases` collection of Sylphx Sandboxes: A Lease is one isolated machine of a shape, region, and image for a bounded time."
type: reference
product: sandboxes
summary: "A Lease is one isolated machine of a shape, region, and image for a bounded time."
updated: 2026-09-28
order: 900
---

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`](/docs/api/leases#get) | Gets a lease. |
| `GET` | [`list`](/docs/api/leases#list) | Lists leases in a environment. Filter on `meta.labels` (for example `labels.agent = "a_123"`), `status.state`, and `spec.kind`. |
| `POST` | [`create`](/docs/api/leases#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`](/docs/api/leases#renew) | Extends `expire_time`, never past the shape's longest lease. Does not change the generation. |
| `POST` | [`release`](/docs/api/leases#release) | Ends a lease with END_REASON_RELEASED; the machine is destroyed and never leased again, and attached volumes are detached. |
| `POST` | [`pause`](/docs/api/leases#pause) | Pauses a lease: its disk is kept and its machine destroyed; the generation increases. Process memory is not kept. |
| `POST` | [`resume`](/docs/api/leases#resume) | Resumes a paused lease on a machine granted now, or refuses it; the generation increases. |
| `POST` | [`set_network`](/docs/api/leases#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`](/docs/api/leases#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`](/docs/api/leases#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`](/docs/api/leases#read-file) | Reads one file from the lease, at most 16 MiB; larger files use the guest's `/files`. |
| `POST` | [`write_file`](/docs/api/leases#write-file) | Writes one file in the lease, at most 16 MiB, creating parent directories. |
| `POST` | [`list_files`](/docs/api/leases#list-files) | Lists one directory in the lease. |
| `POST` | [`remove_file`](/docs/api/leases#remove-file) | Removes one file or directory tree in the lease. |
| `POST` | [`open_port`](/docs/api/leases#open-port) | Exposes a guest port. |
| `POST` | [`close_port`](/docs/api/leases#close-port) | Stops exposing a guest port. |
| `POST` | [`act`](/docs/api/leases#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`](/docs/api/leases#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`](/docs/api/leases#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`](/docs/api/leases#release-control) | Releases control held under `epoch`; its controller tokens stop working. |
| `GET` | [`get_control`](/docs/api/leases#get-control) | Gets who holds control of a lease's display. |
| `POST` | [`install_app`](/docs/api/leases#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](/docs/api/leases/get)

## 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](/docs/api/leases/list)

## 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](/docs/api/leases/create)

## 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](/docs/api/leases/renew)

## 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](/docs/api/leases/release)

## 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](/docs/api/leases/pause)

## 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](/docs/api/leases/resume)

## 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](/docs/api/leases/set_network)

## 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](/docs/api/leases/mint_token)

## 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](/docs/api/leases/exec)

## 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](/docs/api/leases/read_file)

## 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](/docs/api/leases/write_file)

## 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](/docs/api/leases/list_files)

## 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](/docs/api/leases/remove_file)

## 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](/docs/api/leases/open_port)

## 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](/docs/api/leases/close_port)

## 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](/docs/api/leases/act)

## 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](/docs/api/leases/open_stream)

## 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](/docs/api/leases/acquire_control)

## 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](/docs/api/leases/release_control)

## 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](/docs/api/leases/get_control)

## 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](/docs/api/leases/install_app)