curl -X POST "https://app.runtm.com/api/v2/sessions/86e11104-.../start" \
-H "Authorization: Bearer runtm_xxx"
import requests
response = requests.post(
"https://app.runtm.com/api/v2/sessions/86e11104-.../start",
headers={"Authorization": "Bearer runtm_xxx"},
)
session = response.json()
print(f"Sandbox {session['sandbox']['sandbox_id']} is {session['state']}")
const response = await fetch(
"https://app.runtm.com/api/v2/sessions/86e11104-.../start",
{ method: "POST", headers: { "Authorization": "Bearer runtm_xxx" } }
);
const session = await response.json();
console.log(`Sandbox ${session.sandbox.sandbox_id} is ${session.state}`);
{
"id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b",
"state": "running",
"agent": "claude-code",
"template": null,
"name": "Refactor billing service",
"github_repo": "acme/billing",
"github_branch": "agent/86e11104",
"workspace_path": "/home/user",
"organization_id": "org_abc123",
"created_at": "2026-05-09T21:00:00Z",
"updated_at": "2026-05-09T21:30:00Z",
"services": { "frontend": 3000 },
"env": { "NODE_ENV": "*****" },
"visibility": "private",
"total_cost_usd": 0.23,
"tabs": [{ "id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b", "name": "Chat 1" }],
"org_template_repos": null,
"sandbox": {
"sandbox_id": "sb_xyz",
"state": "running",
"started_at": "2026-05-09T21:00:30Z",
"end_at": "2026-05-09T22:00:30Z"
}
}
Start Sandbox (v2)
Ensure the sandbox is running - resumes if paused, waits if provisioning
POST
/
api
/
v2
/
sessions
/
{session_id}
/
start
curl -X POST "https://app.runtm.com/api/v2/sessions/86e11104-.../start" \
-H "Authorization: Bearer runtm_xxx"
import requests
response = requests.post(
"https://app.runtm.com/api/v2/sessions/86e11104-.../start",
headers={"Authorization": "Bearer runtm_xxx"},
)
session = response.json()
print(f"Sandbox {session['sandbox']['sandbox_id']} is {session['state']}")
const response = await fetch(
"https://app.runtm.com/api/v2/sessions/86e11104-.../start",
{ method: "POST", headers: { "Authorization": "Bearer runtm_xxx" } }
);
const session = await response.json();
console.log(`Sandbox ${session.sandbox.sandbox_id} is ${session.state}`);
{
"id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b",
"state": "running",
"agent": "claude-code",
"template": null,
"name": "Refactor billing service",
"github_repo": "acme/billing",
"github_branch": "agent/86e11104",
"workspace_path": "/home/user",
"organization_id": "org_abc123",
"created_at": "2026-05-09T21:00:00Z",
"updated_at": "2026-05-09T21:30:00Z",
"services": { "frontend": 3000 },
"env": { "NODE_ENV": "*****" },
"visibility": "private",
"total_cost_usd": 0.23,
"tabs": [{ "id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b", "name": "Chat 1" }],
"org_template_repos": null,
"sandbox": {
"sandbox_id": "sb_xyz",
"state": "running",
"started_at": "2026-05-09T21:00:30Z",
"end_at": "2026-05-09T22:00:30Z"
}
}
Reconciles the session’s sandbox with the sandbox provider and ensures it is in
Required scope:
running state. Unlike the legacy POST /api/sessions/{session_id}/start, this endpoint only handles sandbox lifecycle. It does not start a dev server or detect preview ports. Dev-server orchestration lives on dedicated endpoints (e.g. POST /api/v2/sessions/{id}/connect).
State transitions handled:
| Current state | Action |
|---|---|
creating | Polls until provisioning finishes (up to 120s) |
paused | Resumes the sandbox via the provider and updates the DB |
running | No-op - returns current state |
destroyed / error | 410 Gone |
| Sandbox missing in provider | Marks session destroyed and returns 410 |
sessions:write
Path Parameters
Headers
Response
200 OK with a SessionV2 object.
Named services exposed by the sandbox, e.g.
{ "frontend": 3000, "postgres": 5432 }. Powers multi-port previews via /connect.Ordered list of agent tabs:
[{ "id": "<uuid>", "name": "Chat 1" }]. Defaults to one tab whose id equals the session id.Live sandbox info from the provider:
sandbox_id- sandbox identifierstate-runningorpausedstarted_at- ISO 8601end_at- ISO 8601 expiry
Errors
| Status | Meaning |
|---|---|
404 | Session not found or not owned by the caller |
410 | Session destroyed, errored, or sandbox expired |
502 | Sandbox not reachable / failed to resume |
503 | Provisioning still in progress after 120s |
curl -X POST "https://app.runtm.com/api/v2/sessions/86e11104-.../start" \
-H "Authorization: Bearer runtm_xxx"
import requests
response = requests.post(
"https://app.runtm.com/api/v2/sessions/86e11104-.../start",
headers={"Authorization": "Bearer runtm_xxx"},
)
session = response.json()
print(f"Sandbox {session['sandbox']['sandbox_id']} is {session['state']}")
const response = await fetch(
"https://app.runtm.com/api/v2/sessions/86e11104-.../start",
{ method: "POST", headers: { "Authorization": "Bearer runtm_xxx" } }
);
const session = await response.json();
console.log(`Sandbox ${session.sandbox.sandbox_id} is ${session.state}`);
{
"id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b",
"state": "running",
"agent": "claude-code",
"template": null,
"name": "Refactor billing service",
"github_repo": "acme/billing",
"github_branch": "agent/86e11104",
"workspace_path": "/home/user",
"organization_id": "org_abc123",
"created_at": "2026-05-09T21:00:00Z",
"updated_at": "2026-05-09T21:30:00Z",
"services": { "frontend": 3000 },
"env": { "NODE_ENV": "*****" },
"visibility": "private",
"total_cost_usd": 0.23,
"tabs": [{ "id": "86e11104-cdbb-42c9-bdc3-5212024ddb7b", "name": "Chat 1" }],
"org_template_repos": null,
"sandbox": {
"sandbox_id": "sb_xyz",
"state": "running",
"started_at": "2026-05-09T21:00:30Z",
"end_at": "2026-05-09T22:00:30Z"
}
}