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
string
required
The session ID.
Headers
string
required
Bearer token. Example:
Bearer runtm_xxxstring
Required when the session belongs to an organization.
Response
200 OK with a SessionV2 object.
string
Session ID.
string
Live sandbox state -
running or paused.string
Coding agent.
string | null
Template the session was scaffolded from.
string | null
Display name.
string | null
GitHub
owner/repo link.string | null
Active branch in the sandbox.
string
Working directory inside the sandbox (e.g.
/home/user).string | null
Owning organization.
string
ISO 8601 creation timestamp.
string | null
ISO 8601 last update timestamp.
object
Named services exposed by the sandbox, e.g.
{ "frontend": 3000, "postgres": 5432 }. Powers multi-port previews via /connect.object
Env var names with masked values (
*****). Secret values are never returned.string
private or team.number
Aggregate cost across all prompts.
array
Ordered list of agent tabs:
[{ "id": "<uuid>", "name": "Chat 1" }]. Defaults to one tab whose id equals the session id.array | null
Multi-repo template entries (only set when the org template defines >1 repo).
object
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"
}
}