Docks

A Dock is an isolated Linux machine; see Docks and Runtimes and images. Routes return the Dock object. All routes need an API key or session and org role member unless stated. Shared rules (envelope, errors, idempotency) are in Conventions.

Size fields share the same limits wherever they appear:

The upper bounds are validation limits; placement also needs a host with room, or the call fails with capacity_exhausted (503).

Lifecycle calls (stop, resume, branch, delete) can also fail with dock_busy (409) while the host is busy with another operation on the same Dock; retry shortly.

POST /v1/docks

Create a Dock (201) and return it once the host has made it ready.

Auth: API key or session. Role: member of the workspace's organization. Accepts idempotency-key.

Response: the Dock object.

An image outside the catalog fails with image_unknown (400). A catalog image that no online host serves fails with image_unavailable (400); retry later or pick an available image from GET /v1/images.

Errors: validation_error (including a size larger than every online host), image_unknown, image_unavailable, dock_not_found (unknown workspace), environment_not_found, environment_secrets_admin_only, connector_admin_only (members, when the Dock has connectors or from names a Template saved from a Dock with connectors), template_not_found, template_source_missing, dock_name_taken, capacity_exhausted, no_host_capacity, base_image_unavailable, subscription_required, concurrency_exceeded, budget_exceeded, idempotency_key_reused, idempotency_in_progress.

GET /v1/docks

List Docks across your organizations.

Response: an array of Dock objects. Errors: validation_error.

GET /v1/docks/:id

Read one Dock. Dock-bound keys may call this for their own Dock.

Response: the Dock object. Errors: dock_not_found.

PATCH /v1/docks/:id

Update a Dock. Every field is optional.

A new size can only be set while the Dock is archived; it applies on the next resume.

Response: the Dock object. Errors: validation_error, dock_not_found, dock_name_taken, conflict (size changed while the Dock is not archived, or diskGiB below the data it holds).

DELETE /v1/docks/:id

Delete a Dock and its Snapshots (202).

Role: the Dock's creator, or admin. Needs x-confirm-delete: <dock id>.

Response: { "operation": { ... } }, an operation. Errors: confirm_required, dock_not_found, dock_delete_forbidden, snapshot_in_use (a Template boots from one of its Snapshots), conflict, dock_busy.

POST /v1/docks/:id/stop

Stop a Dock and save its state as a Snapshot (202). Stopping an archived or archiving Dock returns its current state.

In an organization with retention enabled, a stop without force deletes the Dock's data, so it needs the Dock's creator or admin.

Response: { "id": "...", "state": "archived" }, or "archiving" when a stop is already under way. Errors: dock_not_found, dock_delete_forbidden, conflict (the Dock's state cannot stop), dock_busy, service_unavailable (the final Snapshot failed; the Dock keeps running and its billing is paused).

POST /v1/docks/:id/resume

Boot an archived Dock from its latest Snapshot (202).

Response: { "id": "...", "state": "..." }. Errors: validation_error (including a ttlSeconds out of range), dock_not_found, environment_not_found, conflict (the Dock is not archived, or has no completed Snapshot), environment_secrets_admin_only, capacity_exhausted, no_host_capacity, base_image_unavailable, image_unavailable (no online host serves the Dock's image), dock_busy, subscription_required, concurrency_exceeded, budget_exceeded.

POST /v1/docks/:id/branch

Copy a Dock into a new one (201): the source is captured and the copy starts from that Snapshot.

Accepts idempotency-key.

Response: the Dock object. Errors: as for POST /v1/docks (an image outside the catalog is image_unknown; a different catalog image is validation_error), plus dock_not_found and dock_busy.

POST /v1/docks/:id/exec

Run one command in a ready Dock and return its bounded output.

Accepts idempotency-key (1 to 255 characters); a replay with the same key returns the first command's result, whatever the body, and never runs it twice. The command runs as the Dock user under bash -lc. Not available on Docks driven by a Run. Rate limits are in Conventions.

Response:

{ "exitCode": 0, "stdout": "hello\n", "stderr": "", "durationMs": 214, "truncated": false }

stdout and stderr are UTF-8, each clipped to its first 1 MiB, and truncated is true when either was clipped. Errors: validation_error, dock_not_found, environment_secrets_admin_only, dock_not_running, exec_unavailable, exec_timeout, exec_busy, exec_failed, exec_result_expired, rate_limited.

POST /v1/docks/:id/terminal

Issue a single-use terminal ticket (201). Open the terminal WebSocket at GET /v1/docks/:id/terminal?ticket=<ticket> before it expires.

No body. Response:

{ "ticket": "...", "expiresAt": "2026-01-01T12:00:30.000Z" }

The ticket is valid for 30 seconds. A terminal closes after 30 idle minutes or 12 hours. Errors: dock_not_found, environment_secrets_admin_only, dock_not_running, exec_unavailable, rate_limited.

GET /v1/docks/:id/ports

List exposed ports. Dock-bound keys may call this for their own Dock.

Response: an array of { "port": 3000, "url": "https://...", "createdAt": "..." }. url is null while hosted ports are off. Errors: dock_not_found, environment_secrets_admin_only.

POST /v1/docks/:id/ports

Expose a Dock port at a public URL (201). Exposing a port again returns the same URL. Dock-bound keys may call this for their own Dock. A Dock exposes at most 10 ports.

Response: { "port": 3000, "url": "https://...", "createdAt": "..." }. Errors: validation_error, dock_not_found, environment_secrets_admin_only, port_limit_reached, ports_unavailable.

DELETE /v1/docks/:id/ports/:port

Stop exposing a port. Dock-bound keys may call this for their own Dock.

Response: { "deleted": true }. Errors: dock_not_found, environment_secrets_admin_only, port_not_found.

GET /v1/docks/:id/stats

Read the Dock's current resource sample and an optional aggregate. Dock-bound keys may call this for their own Dock.

Response:

{
  "dockId": "...",
  "state": "ready",
  "sample": { "dockId": "...", "at": "...", "cpuPercent": 3.2, "memBytes": 0, "memLimit": 0, "diskBytes": 0, "rxBytes": 0, "txBytes": 0, "source": "..." },
  "window": { "window": "1h", "samples": 60, "avg": { "cpuPercent": 2.1, "memBytes": 0, "memLimit": 0, "diskBytes": 0, "rxBytes": 0, "txBytes": 0 }, "peak": { "cpuPercent": 9.8, "memBytes": 0, "memLimit": 0, "diskBytes": 0, "rxBytes": 0, "txBytes": 0 } }
}

sample is null when no sample has arrived yet, and carries a containers array when the Dock reports per-container usage; window is present only when requested. Errors: validation_error, dock_not_found.

GET /v1/operations/:id

Poll an operation. Operations belong to the organization of the thing they changed; ones you cannot see read as not found.

Response: the operation object. Errors: operation_not_found.