Stateless execution
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, node, or bun |
code | yes | Source to run |
dependencies | no | pip/npm packages installed before run |
volume_id | no | Attach a persistent volume you already created via POST /v1/volumes. Naming an id you don't own, or one that doesn't exist, is a 404. See Volumes |
timeout_ms | no | Wall-clock cap (default 30s) |
size | no | small, medium, or large. Omitted uses the server's default tier |
template | no | Base environment to start from. Empty or base uses the default base template. See Templates |
no_sudo | no | Run in hardened mode for untrusted code — the default user loses passwordless sudo |
project_id | no | Attribute the run to this project instead of the credential's default |
command_capture | no | Command metadata retained in the execution log: hash, executable (default), or full |
Response 200
{
"session_id": "2476b0a6-722e-4bd9-9f25-771ccbdd53bd",
"stdout": "6\n",
"stderr": "",
"exit_code": 0,
"duration_ms": 842,
"install_ms": 0,
"restore_ms": 0,
"phase": "run",
"timed_out": false
}session_id is the throwaway session used for the run (useful for audit/history). restore_ms is set when the run woke from a paused baseline.
When to use stateless execution vs sessions
Stateless execution (/v1/sessions/exec) | Sessions |
|---|---|
| Run and return, nothing to track | Multi-step workflows |
| No state across calls | Warm wake; state persists |
| Simplest integration | Files, ports, fork, pause |
A stateless-execution 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.