Console

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

Create a lease

Creates a lease: granted now and returned READY (or GRANTED when `wait_ready` is false), or refused with a typed error.

Checked 2026-09-28

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.

Path POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases
Scope sandboxes:write
Effect write — a successful call changes state.
Collection leases
Query lease_id, validate_only, skip_wait_ready

#Request

Field	Type	What it is
`parent`	`string`	The parent to create in. Required.
`lease`	`Lease`	The lease to create; only spec and caller-writable metadata are read. Required.
`lease_id`	`string`	The id segment of the name; the server assigns one when unset.
`validate_only`	`bool`	Validate and return the result without writing anything.
`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.

#Lease

Field	Type	What it is
`name`	`string`	`orgs/{org}/projects/{project}/envs/{env}/leases/{lease}`.
`meta`	`ResourceMeta`	Resource metadata.
`spec`	`LeaseSpec`	Desired state. Required.

#ResourceMeta

Field	Type	What it is
`labels`	`map<string, string>`	Caller-writable, indexed labels (AIP-122 label rules).
`annotations`	`map<string, string>`	Caller-writable, unindexed annotations.
`display_name`	`string`	Caller-writable human-readable name.

#LeaseSpec

Field	Type	What it is
`shape`	`string`	The shape. Required.
`image`	`string`	The image: an artifact in Sylphx Artifacts, by digest, or `template:<name>` (`base`, `desktop`, `browser`, `android`). Ignored when `source_snapshot` is set.
`kind`	`LeaseKind`	What the machine serves; default GENERAL. One of `general`, `browser`, `desktop`, `android`.
`region`	`string`	The region; default the project's home region.
`pool`	`string`	The Pool to take a warm machine from; default the platform pool for the shape and image.
`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.
`idle_timeout`	`duration`	End the lease IDLE after no data-plane call, stream input, or exec for this long; unset never idles out.
`network`	`LeaseNetwork`	The outbound policy. Change it on a running lease with `:setNetwork`.
`ports`	`LeasePort[]`	Guest ports to expose.
`env`	`map<string, string>`	Plain environment variables. Secrets bind through Sylphx Secrets, never here.
`volumes`	`VolumeMount[]`	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.
`budget`	`LeaseBudget`	Spend bounds beyond `ttl` and `idle_timeout`.
`display`	`DisplaySpec`	The display of a DESKTOP, BROWSER, or ANDROID lease.
`browser`	`BrowserSpec`	The browser of a BROWSER lease.
`source_snapshot`	`string`	Boot from this Snapshot's disk and image instead of `image`.
`webhook`	`LeaseWebhook`	Where lease events are delivered as signed webhooks, in addition to `leases/*/events`.
`device`	`DeviceSpec`	The device of an ANDROID lease: model and OS version. The device sets the display; `display` is ignored.

#LeaseNetwork

Field	Type	What it is
`egress`	`EgressPolicy`	Default ALLOW. One of `allow`, `deny`, `allowlist`.
`allowed_domains`	`string[]`	Hosts reachable when `egress` is ALLOWLIST: exact names or one leading `.` wildcard label, for example `api.openai.com`, `.github.com`.
`allowed_cidrs`	`string[]`	Public CIDRs reachable when `egress` is ALLOWLIST.

#LeasePort

Field	Type	What it is
`port`	`int32`	The guest port. Required.
`visibility`	`PortVisibility`	Default PRIVATE: a lease token or an Access key with `sandboxes:exec` is required. One of `private`, `public`.

#VolumeMount

Field	Type	What it is
`volume`	`string`	The volume. Required.
`mount_path`	`string`	The absolute guest path; default `/home/user/volumes/{volume id}`.
`read_only`	`bool`	Mount read-only.

#LeaseBudget

Field	Type	What it is
`max_cpu_seconds`	`int64`	End CPU_BUDGET after this many vCPU-seconds of guest CPU time.
`max_cost_micros`	`int64`	End COST_BUDGET once the shape's list price times wall seconds reaches this many millionths of a US dollar.

#DisplaySpec

Field	Type	What it is
`width`	`int32`	Logical width in pixels; default 1280.
`height`	`int32`	Logical height in pixels; default 800.
`dpi`	`int32`	Dots per inch; default 96.

#BrowserSpec

Field	Type	What it is
`headless`	`bool`	Run headless instead of on the display. A headless browser has no stream and no computer actions; CDP only.
`user_data_dir`	`string`	The profile directory; put it on a volume to keep cookies and storage across leases. Default a fresh profile.
`start_url`	`string`	The page opened at start; default `about:blank`.

#LeaseWebhook

Field	Type	What it is
`uri`	`string`	The HTTPS URL that receives the POSTs. Required.
`kinds`	`LeaseEventKind[]`	Deliver only these kinds; default every kind. One of `granted`, `ready`, `refused`, `ended`, `renewed`, `network_changed`, `control_acquired`, `control_released`, `control_expired`, `budget_warning`, `paused`, `resumed`.

#DeviceSpec

Field	Type	What it is
`model`	`string`	A model id from the device catalog, e.g. `pixel_7`; default `pixel_7`.
`os_version`	`string`	The OS version, e.g. `14`; default the newest offered.

#Response

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.

#ResourceMeta

Field	Type	What it is
`generation`	`int64`	Increases by one on every change to `spec`. Output only.
`etag`	`string`	Strong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as `If-Match` or `etag` to make Update and Delete conditional; a mismatch fails with ABORTED / 409 `ETAG_MISMATCH`. Output only.
`create_time`	`timestamp`	When the Resource was created. Output only.
`update_time`	`timestamp`	When the Resource last changed. Output only.
`delete_time`	`timestamp`	Set while the Resource is being deleted. Output only.
`labels`	`map<string, string>`	Caller-writable, indexed labels (AIP-122 label rules).
`annotations`	`map<string, string>`	Caller-writable, unindexed annotations.
`display_name`	`string`	Caller-writable human-readable name.
`creator`	`string`	The principal that created the Resource. Output only.

#LeaseSpec

Field	Type	What it is
`shape`	`string`	The shape. Required.
`image`	`string`	The image: an artifact in Sylphx Artifacts, by digest, or `template:<name>` (`base`, `desktop`, `browser`, `android`). Ignored when `source_snapshot` is set.
`kind`	`LeaseKind`	What the machine serves; default GENERAL. One of `general`, `browser`, `desktop`, `android`.
`region`	`string`	The region; default the project's home region.
`pool`	`string`	The Pool to take a warm machine from; default the platform pool for the shape and image.
`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.
`idle_timeout`	`duration`	End the lease IDLE after no data-plane call, stream input, or exec for this long; unset never idles out.
`network`	`LeaseNetwork`	The outbound policy. Change it on a running lease with `:setNetwork`.
`ports`	`LeasePort[]`	Guest ports to expose.
`env`	`map<string, string>`	Plain environment variables. Secrets bind through Sylphx Secrets, never here.
`volumes`	`VolumeMount[]`	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.
`budget`	`LeaseBudget`	Spend bounds beyond `ttl` and `idle_timeout`.
`display`	`DisplaySpec`	The display of a DESKTOP, BROWSER, or ANDROID lease.
`browser`	`BrowserSpec`	The browser of a BROWSER lease.
`source_snapshot`	`string`	Boot from this Snapshot's disk and image instead of `image`.
`webhook`	`LeaseWebhook`	Where lease events are delivered as signed webhooks, in addition to `leases/*/events`.
`device`	`DeviceSpec`	The device of an ANDROID lease: model and OS version. The device sets the display; `display` is ignored.

#LeaseStatus

Field	Type	What it is
`observed_generation`	`int64`	The generation this status was computed from. Output only.
`conditions`	`Condition[]`	Ready, Reconciling, Stalled. Output only.
`state`	`LeaseState`	The state machine. Output only. One of `requested`, `granted`, `ready`, `paused`, `ending`, `ended`, `refused`.
`lease_generation`	`int64`	Increases on grant, pause, resume, and end; every token and platform command carries it, and a stale one is refused STALE_GENERATION. Output only.
`short_id`	`string`	Eight Crockford base32 characters naming the lease in data-plane routes. Output only.
`endpoints`	`LeaseEndpoints`	Data-plane addresses. Output only.
`refusal`	`LeaseRefusal`	Why the lease was refused, when `state` is REFUSED. Output only. One of `no_capacity`, `no_matching_cell`, `shape_not_offered`, `shape_not_entitled`, `image_not_found`, `abuse_hold`.
`end_reason`	`EndReason`	Why the lease ended, once `state` is ENDING or ENDED. Output only. One of `released`, `expired`, `idle`, `cpu_budget`, `cost_budget`, `abuse`, `quota`, `org_deleted`, `machine_lost`, `boot_failed`.
`grant_time`	`timestamp`	When a machine was assigned. Output only.
`ready_time`	`timestamp`	When the guest became ready. Output only.
`expire_time`	`timestamp`	When the lease ends unless renewed. Output only.
`end_time`	`timestamp`	When the lease ended. Output only.
`usage`	`LeaseUsage`	What the lease has consumed so far. Output only.
`control`	`ControlState`	Who holds input control of the display. Output only.
`display`	`DisplayInfo`	The effective display, for kinds that have one. Output only.
`network`	`LeaseNetwork`	The effective outbound policy, including the ranges always blocked. Output only.

#LeaseNetwork

Field	Type	What it is
`egress`	`EgressPolicy`	Default ALLOW. One of `allow`, `deny`, `allowlist`.
`allowed_domains`	`string[]`	Hosts reachable when `egress` is ALLOWLIST: exact names or one leading `.` wildcard label, for example `api.openai.com`, `.github.com`.
`allowed_cidrs`	`string[]`	Public CIDRs reachable when `egress` is ALLOWLIST.
`blocked_cidrs`	`string[]`	The ranges blocked under every policy. Output only.

#LeasePort

Field	Type	What it is
`port`	`int32`	The guest port. Required.
`visibility`	`PortVisibility`	Default PRIVATE: a lease token or an Access key with `sandboxes:exec` is required. One of `private`, `public`.
`uri`	`string`	The port's URL. Output only.

#VolumeMount

Field	Type	What it is
`volume`	`string`	The volume. Required.
`mount_path`	`string`	The absolute guest path; default `/home/user/volumes/{volume id}`.
`read_only`	`bool`	Mount read-only.

#LeaseBudget

Field	Type	What it is
`max_cpu_seconds`	`int64`	End CPU_BUDGET after this many vCPU-seconds of guest CPU time.
`max_cost_micros`	`int64`	End COST_BUDGET once the shape's list price times wall seconds reaches this many millionths of a US dollar.

#DisplaySpec

Field	Type	What it is
`width`	`int32`	Logical width in pixels; default 1280.
`height`	`int32`	Logical height in pixels; default 800.
`dpi`	`int32`	Dots per inch; default 96.

#BrowserSpec

Field	Type	What it is
`headless`	`bool`	Run headless instead of on the display. A headless browser has no stream and no computer actions; CDP only.
`user_data_dir`	`string`	The profile directory; put it on a volume to keep cookies and storage across leases. Default a fresh profile.
`start_url`	`string`	The page opened at start; default `about:blank`.

#LeaseWebhook

Field	Type	What it is
`uri`	`string`	The HTTPS URL that receives the POSTs. Required.
`kinds`	`LeaseEventKind[]`	Deliver only these kinds; default every kind. One of `granted`, `ready`, `refused`, `ended`, `renewed`, `network_changed`, `control_acquired`, `control_released`, `control_expired`, `budget_warning`, `paused`, `resumed`.

#DeviceSpec

Field	Type	What it is
`model`	`string`	A model id from the device catalog, e.g. `pixel_7`; default `pixel_7`.
`os_version`	`string`	The OS version, e.g. `14`; default the newest offered.

#Condition

Field	Type	What it is
`type`	`string`	The condition type, for example `Ready`.
`status`	`ConditionStatus`	Whether the condition holds. One of `true`, `false`, `unknown`.
`observed_generation`	`int64`	The generation this observation was made against.
`reason`	`string`	A machine-readable UpperCamelCase reason.
`message`	`string`	A customer-safe human-readable message.
`severity`	`Severity`	How severe a FALSE condition is. One of `info`, `warning`, `error`.
`transition_time`	`timestamp`	When `status` last changed.

#LeaseEndpoints

Field	Type	What it is
`guest_uri`	`string`	The guest daemon: the E2B envd protocol (Connect-RPC `process.Process`, `filesystem.Filesystem`, HTTP `/files`), routed by the `E2b-Sandbox-Id` header, for streaming exec and PTYs. Output only.
`cdp_uri`	`string`	The Chrome DevTools Protocol WebSocket of a BROWSER lease. Output only.
`e2b_sandbox_id`	`string`	The E2B sandbox id this lease answers to on the E2B-compatible API. Output only.

#LeaseUsage

Field	Type	What it is
`wall_seconds`	`int64`	Wall seconds from grant. Output only.
`cpu_seconds`	`int64`	Guest vCPU-seconds. Output only.
`cost_micros`	`int64`	List-price cost so far, in millionths of a US dollar; 0 on classes that are not priced. Output only.
`measure_time`	`timestamp`	When this usage was measured. Output only.
`memory_gib_seconds`	`int64`	Memory GiB-seconds (shape memory times wall seconds). Output only.
`egress_bytes`	`int64`	Bytes sent to the internet. Output only.
`stream_seconds`	`int64`	Seconds of live stream viewing, summed over viewers. Output only.

#ControlState

Field	Type	What it is
`holder`	`ControlHolder`	Who holds control; UNSPECIFIED when nobody does (agent actions allowed). Output only. One of `agent`, `human`.
`epoch`	`int64`	Increases on every acquire; release names it. Output only.
`principal`	`string`	The Access principal that acquired control. Output only.
`holder_label`	`string`	The caller's label for the person or agent, for example a user id. Output only.
`acquire_time`	`timestamp`	When control was acquired. Output only.
`expire_time`	`timestamp`	When control lapses unless re-acquired. Output only.

#DisplayInfo

Field	Type	What it is
`width`	`int32`	Logical width in pixels; action coordinates are in this space. Output only.
`height`	`int32`	Logical height in pixels. Output only.
`dpi`	`int32`	Dots per inch. Output only.

#Errors

UNAUTHENTICATED — No valid key or token was presented.
PERMISSION_DENIED — The key lacks the method's permission.
UNKNOWN_FIELD — The request has a field the schema does not know.
INVALID_FIELD — A field failed validation.
RESOURCE_ALREADY_EXISTS — A Resource with this name exists.
RESOURCE_NOT_FOUND — The named Resource does not exist or is not visible.
RESOURCE_IN_USE — The Resource is attached to or held by another Resource, for example a volume attached to a running lease.
IDEMPOTENCY_KEY_REUSED — An Idempotency-Key was reused with another body.
IDEMPOTENCY_IN_PROGRESS — The first call with this Idempotency-Key is still running.
NO_CAPACITY — No machine can be granted now (immediate-or-fail); retry after Retry-After.
SHAPE_NOT_OFFERED — The requested shape or kind is not sold.
PLAN_LIMIT_REACHED — The plan's limit is reached.
SPEND_LIMIT_REACHED — The org's spend limit is reached.

Every error arrives in the body Errors describes.

#Examples

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec":{"shape":"…","ttl":{}}}'

Was this page helpful?

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

Send feedback

Platform links