Start workspace
curl --request POST \
--url http://127.0.0.1:8765/v1/workspaces/{workspace_id}/start \
--header 'Authorization: Bearer <token>'import requests
url = "http://127.0.0.1:8765/v1/workspaces/{workspace_id}/start"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('http://127.0.0.1:8765/v1/workspaces/{workspace_id}/start', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "demo",
"status": "running",
"created_at": "2026-11-07T00:00:00.000Z",
"system_time": null,
"sessions": [
{
"session_id": "01a1b425-ec80-7038-86e0-75b597344043",
"cwd": "/"
},
{
"session_id": "agent",
"cwd": "/"
}
],
"mounts": [
{
"prefix": "/",
"vfs": "ram",
"mode": "write",
"description": "",
"backend": "workspace",
"mountpoint": null
}
],
"internals": null
}Lifecycle
Start workspace
POST
/
v1
/
workspaces
/
{workspace_id}
/
start
Start workspace
curl --request POST \
--url http://127.0.0.1:8765/v1/workspaces/{workspace_id}/start \
--header 'Authorization: Bearer <token>'import requests
url = "http://127.0.0.1:8765/v1/workspaces/{workspace_id}/start"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('http://127.0.0.1:8765/v1/workspaces/{workspace_id}/start', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "demo",
"status": "running",
"created_at": "2026-11-07T00:00:00.000Z",
"system_time": null,
"sessions": [
{
"session_id": "01a1b425-ec80-7038-86e0-75b597344043",
"cwd": "/"
},
{
"session_id": "agent",
"cwd": "/"
}
],
"mounts": [
{
"prefix": "/",
"vfs": "ram",
"mode": "write",
"description": "",
"backend": "workspace",
"mountpoint": null
}
],
"internals": null
}Start the workspace using its saved configuration and retained state. The server checks policies and reloads credentials. If already running, return the existing workspace.
RAM-backed files do not survive a stop/start cycle.
See error examples and recovery steps. The complete OpenAPI contract includes every response schema.
Errors
Errors
| Status | Meaning |
|---|---|
400 | The request is malformed: the body is not JSON (invalid_json) or not a JSON object, a field is missing (missing_field), unknown (unknown_field) or has a wrong value (invalid_value), or the request is otherwise invalid (invalid_request). param names the field at fault. |
401 | The token is missing or wrong (unauthorized). |
403 | The call is refused. A policy refused it (policy_refused, with decision), a mount mode or permission refused it (forbidden), the backend is out of space or quota (storage_full), or the request came for a host or from a browser origin that is not allowed (host_not_allowed, origin_not_allowed). |
404 | The workspace, session, job, file or route does not exist, or the caller may not see it (not_found). |
409 | The request conflicts with the current state. The id or name is taken (already_exists), the workspace is busy on another server or starting or stopping (workspace_busy), the workspace is stopped (workspace_stopped), a file changed since it was read (stale_write), or the state allows no such change (conflict). |
429 | Past a rate limit (rate_limited), or a new session past max_sessions (session_limit). |
503 | The server cannot take the request now. It is at max_workspaces (server_full), shutting down (shutting_down), or no worker can take the request (unavailable). |
Authorizations
Response
200 - application/json
OK