Attach a workspace
Returns a running sandbox for the workspace: the one already running, the sleeping one woken, or a new one. One execution at a time: while another is starting or stopping the call answers 409 workspace_leased. When the host running it has stopped answering, the call answers 409 lease_expired; retrying with takeover: true moves the workspace to a new execution restored from its last saved snapshot, reports what was lost in recovery, and never happens while the old execution's host still lists it. A takeover needs sandbox.destroy as well as sandbox.create, is refused with restore_unavailable when the last snapshot never left the unreachable host, and immediately cuts the old execution off: its keys are revoked, and its open terminals, tunnels and preview sockets are closed.
Authorization
bearerAuth A RemoteHost API key (rh_sk_...) or a user session token.
In: header
Path Parameters
uuidRequest Body
application/json
Optional. An empty body, or any field left out, attaches with the defaults each field names.
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/orgs/string/projects/string/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/attach" \ -H "Content-Type: application/json" \ -d '{}'{ "workspace": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa", "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8", "name": "string", "title": "string", "environmentId": "19f5cc2e-7657-437a-9268-83cd3d563563", "lifetimePolicy": "ephemeral", "expiresAt": "string", "gitBranch": "string", "cpuBaseline": "string", "vmm": "string", "currentCheckpointId": "58a17ea9-e017-4666-a39c-b13b4cc338f7", "status": "active", "lease": { "sandboxId": "5b4b1d3f-21e4-43f6-8ac1-b460b150f885", "epoch": "string", "expiresAt": "string", "live": true }, "createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e", "createdAt": "string", "updatedAt": "string", "lastActivityAt": "string" }, "sandbox": { "id": "string", "org_id": "string", "project_id": "string", "name": "string", "agent": "claude", "status": "provisioning", "mode": "persistent", "region": "string", "persistence_policy": "throwaway_ephemeral", "sandbox_profile": "string", "machine_size": "small", "provider": "string", "vmm": "string", "allocated_vcpu": 0, "allocated_memory_gb": 0, "allocated_disk_gb": 0, "end_user_id": "string", "vm_lost_at": "string", "environment_id": "string", "disk": { "usedBytes": 0, "totalBytes": 0, "availableBytes": 0, "warning": 80, "sampledAt": "string" }, "created_at": "string", "updated_at": "string" }, "attached": "created", "leaseRenewed": true, "recovery": { "supersededSandboxId": "da4d1018-e632-4ad1-ac9c-32cf81770bad", "supersededHolderHealth": "gone", "restoredFrom": "checkpoint", "restoredSnapshotAt": "string", "restoredSnapshotDurable": true, "message": "string" }}Delete a workspace DELETE
Deletes the workspace and destroys every execution of it. Uncommitted work is lost. The workspace is unattachable from the moment the call starts; an execution that cannot be destroyed yet (its host is not answering, or an operation on it is still settling) is listed in executionsPendingCleanup and destroyed automatically once it can be. Needs sandbox.environment.delete, which every role holding sandbox.destroy holds. An API key holds it only when its own scopes name it: an unscoped key and every key template lack it, and are refused with 403. API keys reach these operations only where key access to environments is enabled for this deployment, and then only their principal's own workspaces; until then every API key is refused with 403.
Detach a workspace POST
Saves the workspace's execution and stops it. Answers once the stop is under way; the lease is released when the snapshot commits. Idempotent.