---
# @generated by sylphx-gen 0.1.0 from contracts@e145cc7cf1bc9605f2b27439e5e17ed76a1a2fd7e7021906a013f7565e4a0cd5. Do not edit.
title: "sylphx sandboxes leases"
description: "The sylphx sandboxes leases commands of Sylphx Sandboxes: every verb, with its argument, its flags and a run line."
type: reference
product: sandboxes
summary: "Every sylphx sandboxes leases command: its argument, its flags and a run line."
updated: 2026-09-28
nav: false
---

The `leases` commands of Sylphx Sandboxes, as the CLI spells them: the same
calls as [the `leases` API page](/docs/api/leases), typed for the
shell. [Install, sign in and the grammar](/docs/cli) are on the CLI index.

## get

Gets a lease.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases get orgs/acme/projects/shop/envs/production/leases/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`.

**`PARENT`** — optional: the CLI fills it from the linked project or the
key's scope when it is left out.

**CLI**

```bash
sylphx sandboxes leases list orgs/acme/projects/shop/envs/production
```

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases` · scope `sandboxes:read` · effect `read` · [Request, response and examples](/docs/api/leases/list)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--page-size` | `int` | At most this many; default 50, clamped to 1000. |
| `--page-token` | `string` | `next_page_token` of the previous page. |
| `--filter` | `string` | AIP-160 filter over labels, filterable fields, and Ready. |
| `--order-by` | `string` | AIP-132 ordering over filterable fields. |

## 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.

**`ID`** — The id segment of the new Resource's name; the server assigns one when omitted.

**CLI**

```bash
sylphx sandboxes leases create --parent orgs/acme/projects/shop/envs/production --spec.shape …
```

`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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--parent` | `string` | The parent to create in; defaults to the linked project or the key's scope. |
| `--meta.labels` | `key=value` | Caller-writable, indexed labels (AIP-122 label rules). Repeat the flag for each value. |
| `--meta.annotations` | `key=value` | Caller-writable, unindexed annotations. Repeat the flag for each value. |
| `--meta.display-name` | `string` | Caller-writable human-readable name. |
| `--spec.shape` | `string` | The shape. Required. |
| `--spec.image` | `string` | The image: an artifact in Sylphx Artifacts, by digest, or `template:<name>` (`base`, `desktop`, `browser`, `android`). Ignored when `source_snapshot` is set. |
| `--spec.kind` | `enum` | What the machine serves; default GENERAL. One of `general`, `browser`, `desktop`, `android`. |
| `--spec.region` | `string` | The region; default the project's home region. |
| `--spec.pool` | `string` | The Pool to take a warm machine from; default the platform pool for the shape and image. |
| `--spec.ttl` | `duration` | The maximum wall time from grant: 1 minute to 24 hours for microVMs, 24 hours to 30 days for macOS. `:renew` extends it within the shape's bound. Reaching it ends the lease EXPIRED. Required. |
| `--spec.idle-timeout` | `duration` | End the lease IDLE after no data-plane call, stream input, or exec for this long; unset never idles out. |
| `--spec.network.egress` | `enum` | Default ALLOW. One of `allow`, `deny`, `allowlist`. |
| `--spec.network.allowed-domains` | `string` | Hosts reachable when `egress` is ALLOWLIST: exact names or one leading `*.` wildcard label, for example `api.openai.com`, `*.github.com`. Repeat the flag for each value. |
| `--spec.network.allowed-cidrs` | `string` | Public CIDRs reachable when `egress` is ALLOWLIST. Repeat the flag for each value. |
| `--spec.ports` | `json` | Guest ports to expose. Repeat the flag for each value. |
| `--spec.env` | `key=value` | Plain environment variables. Secrets bind through Sylphx Secrets, never here. Repeat the flag for each value. |
| `--spec.volumes` | `json` | Volumes attached at grant, each by name. A volume is attached to at most one lease at a time; a volume already attached refuses the lease with RESOURCE_IN_USE. Repeat the flag for each value. |
| `--spec.budget.max-cpu-seconds` | `int` | End CPU_BUDGET after this many vCPU-seconds of guest CPU time. |
| `--spec.budget.max-cost-micros` | `int` | End COST_BUDGET once the shape's list price times wall seconds reaches this many millionths of a US dollar. |
| `--spec.display.width` | `int` | Logical width in pixels; default 1280. |
| `--spec.display.height` | `int` | Logical height in pixels; default 800. |
| `--spec.display.dpi` | `int` | Dots per inch; default 96. |
| `--spec.browser.headless` | `bool` | Run headless instead of on the display. A headless browser has no stream and no computer actions; CDP only. |
| `--spec.browser.user-data-dir` | `string` | The profile directory; put it on a volume to keep cookies and storage across leases. Default a fresh profile. |
| `--spec.browser.start-url` | `string` | The page opened at start; default `about:blank`. |
| `--spec.source-snapshot` | `string` | Boot from this Snapshot's disk and image instead of `image`. |
| `--spec.webhook.uri` | `string` | The HTTPS URL that receives the POSTs. |
| `--spec.webhook.kinds` | `enum` | Deliver only these kinds; default every kind. Repeat the flag for each value. One of `granted`, `ready`, `refused`, `ended`, `renewed`, `network_changed`, `control_acquired`, `control_released`, `control_expired`, `budget_warning`, `paused`, `resumed`. |
| `--spec.device.model` | `string` | A model id from the device catalog, e.g. `pixel_7`; default `pixel_7`. |
| `--spec.device.os-version` | `string` | The OS version, e.g. `14`; default the newest offered. |
| `--dry-run` | `bool` | Validate and print the result without writing (validate_only). |
| `--skip-wait-ready` | `bool` | Return as soon as the machine is granted instead of when the guest is ready. Default false: wait for READY, at most 60 seconds. |

## renew

Extends `expire_time`, never past the shape's longest lease. Does not change the generation.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases renew orgs/acme/projects/shop/envs/production/leases/lease
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:renew` · scope `sandboxes:write` · effect `write` · [Request, response and examples](/docs/api/leases/renew)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--ttl` | `duration` | The new time to live from now. Required. |
| `--etag` | `string` | Act only if the current etag matches. |
| `--dry-run` | `bool` | Validate and print the result without writing (validate_only). |

## release

Ends a lease with END_REASON_RELEASED; the machine is destroyed and never leased again, and attached volumes are detached.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases release orgs/acme/projects/shop/envs/production/leases/lease --yes
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:release` · scope `sandboxes:write` · effect `destructive` · [Request, response and examples](/docs/api/leases/release)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--etag` | `string` | Act only if the current etag matches. |
| `--dry-run` | `bool` | Validate and print the result without writing (validate_only). |
| `--yes` | `bool` | Do not ask before this destructive call. |

## pause

Pauses a lease: its disk is kept and its machine destroyed; the generation increases. Process memory is not kept.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases pause orgs/acme/projects/shop/envs/production/leases/lease
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:pause` · scope `sandboxes:write` · effect `write` · [Request, response and examples](/docs/api/leases/pause)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--etag` | `string` | Act only if the current etag matches. |
| `--dry-run` | `bool` | Validate and print the result without writing (validate_only). |

## resume

Resumes a paused lease on a machine granted now, or refuses it; the generation increases.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases resume orgs/acme/projects/shop/envs/production/leases/lease
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:resume` · scope `sandboxes:write` · effect `write` · [Request, response and examples](/docs/api/leases/resume)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--etag` | `string` | Act only if the current etag matches. |
| `--dry-run` | `bool` | Validate and print the result without writing (validate_only). |

## set-network

Replaces a running lease's outbound policy. The generation does not change; the new policy applies before the call returns.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases set-network orgs/acme/projects/shop/envs/production/leases/lease
```

`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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--network` | `json` | The new outbound policy; replaces the old one whole. Required. |

## 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.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases mint-token orgs/acme/projects/shop/envs/production/leases/lease
```

`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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--scopes` | `enum` | What the token admits. Required. Repeat the flag for each value. One of `guest`, `ports`, `cdp`, `computer`. |
| `--ttl` | `duration` | At most 1 hour and never past the lease's `expire_time`. |

## 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`.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases exec orgs/acme/projects/shop/envs/production/leases/lease
```

`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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--command` | `string` | The program and its arguments. Use `["bash", "-lc", "…"]` for a shell. Required. Repeat the flag for each value. |
| `--working-directory` | `string` | The working directory; default the user's home. |
| `--env` | `key=value` | Extra environment variables. Repeat the flag for each value. |
| `--stdin` | `string` | Bytes written to standard input. |
| `--timeout` | `duration` | Kill the process after this long; default 60 seconds, at most 10 minutes. |
| `--user` | `string` | The guest user; default `user`. `root` is allowed: the whole machine belongs to the lessee. |

## read-file

Reads one file from the lease, at most 16 MiB; larger files use the guest's `/files`.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases read-file orgs/acme/projects/shop/envs/production/leases/lease
```

`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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--path` | `string` | The absolute path in the guest. Required. |

## write-file

Writes one file in the lease, at most 16 MiB, creating parent directories.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases write-file orgs/acme/projects/shop/envs/production/leases/lease
```

`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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--path` | `string` | The absolute path in the guest. Required. |
| `--content` | `string` | The file's bytes. Required. |
| `--mode` | `int` | The file mode bits; default 0644. |
| `--append` | `bool` | Append `content` to the file (created when absent) instead of replacing it, so a file larger than one call uploads in chunks. |

## list-files

Lists one directory in the lease.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases list-files orgs/acme/projects/shop/envs/production/leases/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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--path` | `string` | The absolute directory path in the guest. Required. |
| `--depth` | `int` | Descend this many levels; default 1. |

## remove-file

Removes one file or directory tree in the lease.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases remove-file orgs/acme/projects/shop/envs/production/leases/lease --yes
```

`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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--path` | `string` | The absolute path in the guest. Required. |
| `--yes` | `bool` | Do not ask before this destructive call. |

## open-port

Exposes a guest port.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases open-port orgs/acme/projects/shop/envs/production/leases/lease
```

`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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--port` | `json` | The port to expose. Required. |

## close-port

Stops exposing a guest port.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases close-port orgs/acme/projects/shop/envs/production/leases/lease
```

`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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--port` | `int` | The guest port. Required. |

## 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.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases act orgs/acme/projects/shop/envs/production/leases/lease
```

`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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--actions` | `json` | The actions, performed in order; at most 64. An empty list with `screenshot` set only takes a screenshot. Repeat the flag for each value. |
| `--screenshot` | `json` | Take a screenshot after the last action and return it. |
| `--lease-generation` | `int` | Refuse STALE_GENERATION unless the lease is at this generation; 0 skips the check. |
| `--control-epoch` | `int` | Act under this AGENT control epoch; 0 acts only while nobody holds control. |

## 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).

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases open-stream orgs/acme/projects/shop/envs/production/leases/lease
```

`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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--ttl` | `duration` | How long the token admits a new connection; at most and default 5 minutes. A connected stream ends when the lease generation changes or the token is revoked. |

## 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.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases acquire-control orgs/acme/projects/shop/envs/production/leases/lease
```

`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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--holder` | `enum` | HUMAN or AGENT. Required. One of `agent`, `human`. |
| `--ttl` | `duration` | How long; default 10 minutes, capped at 30 minutes. |
| `--holder-label` | `string` | A label for the holder, for example the person's user id; recorded in the audit events. |
| `--preempt` | `bool` | For HUMAN: take control from another human. |

## release-control

Releases control held under `epoch`; its controller tokens stop working.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases release-control orgs/acme/projects/shop/envs/production/leases/lease
```

`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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--epoch` | `int` | The epoch AcquireLeaseControl returned. Required. |

## get-control

Gets who holds control of a lease's display.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases get-control orgs/acme/projects/shop/envs/production/leases/lease
```

`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.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx sandboxes leases install-app orgs/acme/projects/shop/envs/production/leases/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)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--apk-path` | `string` | The APK's path in the lease (write it with WriteLeaseFile first). Required. |
| `--grant-permissions` | `bool` | Grant every runtime permission the app declares. |