Concepts

Stateless execution vs session

There is one primitive: the session. A stateless-execution run (/v1/sessions/exec, inis run) is just a session collapsed into a single call — it creates a session, runs your command, and tears it down for you.

For agents making many sequential tool calls, keep a session alive. To run a single script without tracking a session, run code directly instead.

Sessions

A session is a persistent sandbox VM. Create it once, call exec/files/expose many times, destroy when done.

• Compute is metered by the millisecond and billed only while live — starting and stopping a session is not billed. A paused session stops the compute charge; a small storage charge for its saved state continues while it sits paused.
• Any operation on a paused session wakes it automatically.
• DELETE /v1/sessions/{id} destroys immediately.

States, timers (idle_timeout_ms, paused_ttl_ms, on_pty_detach, …), wake-on-op, and recipes live on Session lifecycle. Endpoint details are in the Sessions API.

Preview URLs

Expose a port inside the sandbox to get an HTTPS URL routed to your process:

inis sessions expose "$SID" --port 8080

Returns a URL like https://8080-{session_id}.ams1.sb.inis.run (exact host depends on your node). The guest must bind to 0.0.0.0, not 127.0.0.1.

To lock a preview URL down, pass --auth bearer. The expose response then includes an auth_token, and inbound requests must carry an Authorization: Bearer <auth_token> header.

Expose is idempotent: asking for a port that is already exposed the same way returns the URL and token you already have, rather than minting new ones that would break whoever is holding the old one. Pass --rotate when you actually want a fresh token.

Typical flow: start a server in the sandbox with exec, then call expose.

Fork

POST /v1/sessions/{id}/fork with {"count": 10} clones a live session into N independent children — useful for parallel eval or RL rollouts where each variant needs the same starting state.

Each child gets its own session ID and can diverge independently.

Checkpoints

A checkpoint is a named, retained save-point of a live session that you can restore from later. Where fork's copy is ephemeral (used once to seed children, then discarded), a checkpoint is kept until you delete it — and it outlives the session it came from. Destroying a session never deletes its checkpoints; deletion is always explicit.

# Capture a clean baseline of a live session
inis sessions checkpoint "$SID" --name clean

# ...run some untrusted code...

# Roll the same session back to the baseline, in place
inis sessions restore "$SID" --checkpoint clean

Two ways to restore:

• In place (POST /v1/sessions/{id}/restore): stop the session's current VM and bring it back at the checkpoint state, reusing the same session ID. This is the "run untrusted code, then roll back to a clean state" flow — give an agent or an untrusted script a fresh, known-good environment for every attempt.
• To a new session (POST /v1/checkpoints/{cid}/sessions, or inis checkpoints create-session <cid>): start a brand-new session from the checkpoint. The new session diverges independently, so a checkpoint doubles as a template: prepare an environment once, then stamp out fresh sessions from it.

Capturing a checkpoint does not interrupt the source session — it keeps running. Each checkpoint reports its size_bytes; delete checkpoints you no longer need with inis checkpoints delete <cid> to free disk.

For pause vs fork vs checkpoint (and when to use each), see Session lifecycle. Checkpoints are node-local in this release: restore happens on the same node that holds the checkpoint, the same constraint as pause and resume.

Where things run

• Execution API: https://api.inis.run — sandboxes, sessions, exec.
• Control plane: https://app.inis.run — sign-in, API keys, usage, billing.

These are separate services. Your API key works against the execution API; account management uses a browser session on the app.