Core concepts

Interactive sessions

A live sandbox that stays up across many calls — state persists between steps.

A session is a long-lived sandbox. Unlike one-shot runs, the pod stays running between calls, so installed packages, written files, and the working directory all persist. This is the right primitive for multi-step agents, REPL-style interaction, and any workflow where one step builds on the last.

Lifecycle

  1. POST /v1/sessions launches a sandbox and returns 202 with a session_id (status pending).
  2. Poll GET /v1/sessions/{id} until status is ready.
  3. Run exec and read/write files as many times as you need.
  4. DELETE /v1/sessions/{id} to stop it. Idle sessions are also reaped automatically.

exec and file endpoints return 409 Conflict until the session is ready. The SDK's create_sandbox waits for readiness before returning.

With the SDK

python
sbx = qt.create_sandbox("python")            # waits until ready

sbx.files.write("app.py", "print('hello from a session')")
result = sbx.exec(command="python app.py")
print(result.stdout, result.ok)              # "hello from a session\n" True

# state persists across execs:
sbx.exec(command="pip install requests")
sbx.exec("import requests; print(requests.__version__)")

sbx.kill()

# or auto-kill with a context manager:
with qt.create_sandbox("node") as sbx:
    print(sbx.exec("console.log(2 + 2)").stdout)

Raw HTTP

Create a session

bash
curl https://api.quicktane.com/v1/sessions \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"language": "python"}'
json
{
  "session_id": "9f3c…",
  "status": "pending",
  "language": "python",
  "created_at": "2026-07-19T12:00:00.000000Z"
}

Execute code or a command

Provide either code (run in the session's language) or a shell command. Optional language and timeout apply to code.

bash
curl https://api.quicktane.com/v1/sessions/9f3c…/exec \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"command": "python app.py", "timeout": 30}'
json
{ "stdout": "hello from a session\n", "stderr": "", "exit_code": 0, "ok": true }

Write and read files

bash
# write
curl https://api.quicktane.com/v1/sessions/9f3c…/files \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"path": "app.py", "content": "print(42)"}'

# read
curl "https://api.quicktane.com/v1/sessions/9f3c…/files?path=app.py" \
  -H "Authorization: Bearer sk_live_your_key"

Stop the session

bash
curl -X DELETE https://api.quicktane.com/v1/sessions/9f3c… \
  -H "Authorization: Bearer sk_live_your_key"

Billing: a session is metered for its full lifetime, not just active exec time. Always kill() sessions you're done with — idle reaping is a safety net, not a substitute.

Need help? Contact us → Full API reference →