Start

Platform

App store purchases

Auth

Builds

Database

Flags

Hosting

Jobs and cron

Localization

Monitoring

Network

Notifications

Organizations

Payments

Queues

Events

Realtime

Runners

Sandboxes

Storage

Webhooks

Workflows

Getting Started

Installation

Authentication

AI Services

KV Store

Overview

Webhooks

Deploy & Infrastructure

Reference

On this page

get
list
create
renew
release
pause
resume
set-network
mint-token
exec
read-file
write-file
list-files
remove-file
open-port
close-port
act
open-stream
acquire-control
release-control
get-control
install-app

Reference

sylphx sandboxes leases

Every sylphx sandboxes leases command: its argument, its flags and a run line.

Checked 2026-09-28

The leases commands of Sylphx Sandboxes, as the CLI spells them: the same calls as the leases API page, typed for the shell. Install, sign in and the grammar are on the CLI index.

#get

Gets a lease.

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

CLI

Shell

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

#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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

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

Shell

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

#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

Shell

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

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.

Was this page helpful?

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

Send feedback

Platform links