One-shot exec
Run a single command in a throwaway session.
A session is the only primitive. When you just want to run one command and get the output back, /v1/sessions/exec collapses create, run, and destroy into a single call — no session to track, no teardown to remember.
Reach for it for batch jobs, simple tools, and playground runs. For multi-step work where state carries between calls, use sessions instead.
All requests require Authorization: Bearer inis_... and Content-Type: application/json. See Authentication.
Prefer the CLI or an SDK for day-to-day use — the reference below is for custom integrations.
Run code
Run Python or Node source in a fresh sandbox that is destroyed when the run completes.
Request body
{
"language": "python",
"code": "print(6)",
"dependencies": ["pandas"],
"timeout_ms": 30000
}| Field | Required | Description |
|---|---|---|
language | yes | python or node |
code | yes | Source to run |
dependencies | no | pip/npm packages installed before run |
volume_id | no | Persistent volume to mount |
timeout_ms | no | Wall-clock cap (default 30s) |
Response 200
{
"sandbox_id": "V1StGXR8Z5jdHi6BmyT",
"stdout": "6\n",
"stderr": "",
"exit_code": 0,
"duration_ms": 842,
"install_ms": 0,
"phase": "run",
"timed_out": false
}When to use one-shot vs sessions
One-shot (/v1/sessions/exec) | Sessions |
|---|---|
| Run and return, nothing to track | Multi-step workflows |
| No state across calls | ~50ms warm wake; state persists |
| Simplest integration | Files, ports, fork, pause |
A one-shot call is the same session primitive with destroy_on_completion set — you can pass that flag to POST /v1/sessions yourself if you want to run the create and exec steps separately while still skipping persistence.
See Concepts for the full comparison.