Concepts

One-shot vs session

There is one primitive: the session. A one-shot 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, use a one-shot call.

Sessions

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

creating → live → paused → live → destroyed
                ↑                ↓
           wake on op      auto-pause on idle

• Billing runs only while live. Paused and idle sessions are free at launch — no compute or storage charge.
• Any operation on a paused session wakes it automatically.
• DELETE /v1/sessions/{id} destroys immediately.

See Sessions API for the full reference.

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 a one-time auth_token, and inbound requests must carry an Authorization: Bearer <auth_token> header.

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 snapshot of a live session that you can restore from later. Where fork's snapshot 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 sessions create --from-checkpoint <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.

Checkpoint vs fork vs pause, at a glance:

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.