---
# @generated by sylphx-gen 0.1.0 from contracts@e145cc7cf1bc9605f2b27439e5e17ed76a1a2fd7e7021906a013f7565e4a0cd5. Do not edit.
title: "Open port on a lease"
description: "`sandboxes.leases.open_port` (POST /v1/{name}:openPort): Exposes a guest port."
type: reference
product: sandboxes
summary: "Exposes a guest port."
updated: 2026-09-28
nav: false
---

> **This method is not served on the public API.** `api.sylphx.com` does not route this call: its backend is not deployed behind the public API, or does not implement the call. This page documents the contract. It is kept out of the sidebar and of search engines.

Exposes a guest port.

- **Path** `POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:openPort`
- **Scope** `sandboxes:exec`
- **Effect** `write` — a successful call changes state.
- **Collection** [leases](/docs/api/leases)

## Request

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | The name of the lease. Required. |
| `port` | `LeasePort` | The port to expose. Required. |

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

## 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`](/docs/api/errors/UNAUTHENTICATED) — No valid key or token was presented.
- [`PERMISSION_DENIED`](/docs/api/errors/PERMISSION_DENIED) — The key lacks the method's permission.
- [`RESOURCE_NOT_FOUND`](/docs/api/errors/RESOURCE_NOT_FOUND) — The named Resource does not exist or is not visible.
- [`INVALID_STATE`](/docs/api/errors/INVALID_STATE) — The Resource is in a state that forbids the call.
- [`IDEMPOTENCY_KEY_REUSED`](/docs/api/errors/IDEMPOTENCY_KEY_REUSED) — An Idempotency-Key was reused with another body.
- [`IDEMPOTENCY_IN_PROGRESS`](/docs/api/errors/IDEMPOTENCY_IN_PROGRESS) — The first call with this Idempotency-Key is still running.
- [`UNIMPLEMENTED`](/docs/api/errors/UNIMPLEMENTED) — The path or method is not served (yet) at this version.

Every error arrives in the body [Errors](/docs/platform/errors) describes.

## Examples

**cURL**

```curl
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:openPort" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port":{"port":1}}'
```

**TypeScript**

```ts
const response = await sylphx.sandboxes.leases.openPort({ name: 'orgs/acme/projects/shop/envs/production/leases/lease', port: { port: 1 } })
```

**Rust**

```rust
let mut req = sylphx::sandboxes::OpenLeasePortRequest::default();
req.name = "orgs/acme/projects/shop/envs/production/leases/lease".to_string();
req.port = Some(sylphx::sandboxes::LeasePort {
    port: 1,
    ..Default::default()
});
let response = sx.sandboxes().leases().open_port(req).await?;
```

**CLI**

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

**MCP**

```json
{ "method_id": "sandboxes.leases.open_port", "args": {"name":"orgs/acme/projects/shop/envs/production/leases/lease","port":{"port":1}} }
```