Remotehost Docs
API ReferenceWorkspaces

Detach a workspace

POST
/orgs/{orgId}/projects/{projectId}/workspaces/{workspaceId}/detach

Saves the workspace's execution and stops it. Answers once the stop is under way; the lease is released when the snapshot commits. Idempotent.

Authorization

bearerAuth
AuthorizationBearer <token>

A RemoteHost API key (rh_sk_...) or a user session token.

In: header

Path Parameters

orgId*string
projectId*string
workspaceId*string
Formatuuid

Response Body

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/detach"
{  "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"  },  "detached": "stopping"}

Attach a workspace POST

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.

Fork a workspace from a durable checkpoint POST

Creates a new workspace in the same project that starts as a copy of this one at a durable checkpoint: its disk and memory, uncommitted work included. checkpointId defaults to the workspace's head. The fork starts asleep with one stopped execution; the first attach wakes it. It gets its own git branch, remotehost/<name>; nothing is pushed. Needs sandbox.create and sandbox.destroy on the project, and only the workspace's owner may fork it (403 workspace_owner_only). A checkpoint that is not durable yet is refused with 409 checkpoint_not_durable, one of another workspace with 404 checkpoint_not_found, a checkpoint whose saved state is no longer in storage with 409 checkpoint_unavailable, a workspace that is not active or sleeping with 409 workspace_unavailable, and a workspace with no checkpoint at all with 409 nothing_to_fork. The fork keeps the source's lifetimePolicy and has no expiresAt. Off unless the server enables it; while off the route answers 404. A workspace with a work volume is forked with a copy of that volume. A running workspace's volume is committed first, so the copy holds every write made before the fork was asked; a commit that fails or does not answer in time is refused with 409 workspace_unavailable. A fork at a named checkpoint is refused with 409 checkpoint_volume_moved once the volume has changed since that checkpoint, as is a fork of a workspace that is stopping. A copy smaller than 4096 bytes is refused with 409 work_volume_too_small. The copy is refused as a volume create is (409 volume_limit_exceeded, 429 rate_limited, 404 not_found), and with 503 volume_service_unavailable when the volume service does not answer.