Skip to main content

Overview

A session is one running agent, started from an environment. The harness runs unmodified inside an isolated sandbox. You send messages, the agent works, and every step lands in an ordered transcript you can read back or stream live. To work in the sandbox yourself (run a command, copy files, open a shell, expose a port), see Session ops.

Sandbox

Claude Code and custom sessions run in the same sandbox image: Debian 12 with
  • Python 3.11 with pip (also pip3), venv and pipx; python runs python3
  • Node.js 22 with npm and npx
  • git, curl, ripgrep (rg), jq, unzip, procps
  • a C/C++ toolchain (gcc, g++, make) and the Python headers, so packages without a prebuilt wheel still install
The agent runs as the unprivileged user agent (no sudo), with HOME=/home/agent and /workspace as its working directory. pip install <package> installs into the user’s site directory (~/.local); for an isolated environment use python3 -m venv .venv. npm install -g needs root, so install into the project (npm install, npx) instead. OpenCode, Codex, LangGraph and CrewAI sessions run in their own images (see Harnesses); the LangGraph and CrewAI one is Python 3.12 with both frameworks preinstalled (see Bring your own agent). Package downloads are ordinary egress: pip and npm traffic goes through the session’s egress rules like every other request. The default coding preset allows PyPI (pypi.org, files.pythonhosted.org) and npm (registry.npmjs.org); under locked_down add them to allowed_hosts or egress_rules yourself. pip, npm, git, curl and Python already trust the egress proxy’s certificate. Sessions created before pip was added keep the image they started on (a snapshot only restores on the image it was taken on), and so do forks of them: pip is not available there. Start a new session to get it.

Lifecycle

Sessions pause themselves after the environment’s idle_timeout_s without input. Sending a message to a paused session returns 409; call resume first (it takes a few seconds while the workspace is restored). Creating a session answers within 90 seconds. If the sandbox is still starting by then, the response is the session in provisioning and it keeps starting on its own. The same happens when your client disconnects mid-request, so do not retry a create that timed out: list your sessions (GET /v1/sessions) and follow the one it started. A session still provisioning 10 minutes after it was created, resumed or rolled back is failed with failure_code provisioning_timeout, and its keys are revoked.

Pause and resume

A pause snapshots the sandbox’s filesystem and stops the sandbox; a resume starts a fresh sandbox from that snapshot. What survives a pause:
  • Files under /workspace (and anything else the agent wrote to the sandbox’s disk).
  • The conversation: the harness resumes its own transcript, so the agent continues where it left off and the Veri transcript keeps its seq numbering.
What does not survive:
  • Running processes, open ports and background tasks. A dev server or watcher the agent started is gone after resume; the agent has to start it again.
  • Per-session permission grants the agent collected during the run (anything you approved interactively). The environment’s permissions rules apply as written.
  • Any in-memory state of the harness or its tools.
A snapshot is tied to the agent image version it was taken from and expires 30 days after it was taken or last restored. A session paused longer than that cannot be resumed; its transcript stays readable for the usual retention and you can start a new session from the same environment.

Checkpoints, forks and rollbacks

A checkpoint is the same snapshot a pause takes, without the stop: the sandbox’s filesystem and the agent’s position in the conversation, recorded while the session keeps running. From a checkpoint you can fork new sessions or roll the session itself back.
  • Checkpoint (POST /v1/sessions/{id}/checkpoints, optional label): allowed while the session is ready or paused; 409 during a run or while an approval is pending. Taking one stops the harness for the snapshot (about 20 s per GB of workspace) and relaunches it, so the session cannot take a message meanwhile. A paused session’s pause snapshot is recorded as the checkpoint without restarting anything. The transcript gets a session.checkpoint event.
  • Fork (POST /v1/sessions/{id}/fork, {checkpoint_id?, count, budget_usd?, title?}): starts count (1 to 4) new sessions from the checkpoint; without checkpoint_id a fresh checkpoint is taken first. Each child gets the checkpoint’s files and the conversation up to that point, then continues it as its own conversation (the agent remembers everything the parent was told). Children are ordinary sessions: they pin the parent’s environment version and hourly rate, get their own model access key and their own budget_usd (the parent’s unless you pass one), are billed per awake hour individually and each takes a slot under the workspace’s concurrent-session cap. A fork that does not fit under the cap starts no child (429 CONCURRENT_SESSION_LIMIT). Children carry parent_session_id and forked_from_checkpoint_id; the parent’s transcript records session.forked with the children’s ids. Forking needs a harness that can continue a conversation as a new one (claude-code, opencode, codex); a custom harness session returns 409 harness_does_not_support_fork (see Harnesses).
  • Rollback (POST /v1/sessions/{id}/rollback, {checkpoint_id}): puts the session back to the checkpoint in place: same id, same key, same transcript (earlier events stay readable; a session.rolled_back event marks the point). Allowed while ready or paused (409 during a run or while an approval is pending); the session is provisioning until the sandbox is back, like a resume. Rolling back refreshes the checkpoint’s expiry.
What a checkpoint carries is exactly what a pause carries: files on the sandbox’s disk and the conversation. Running processes, open ports, background tasks and in-memory state are not part of it, in children or after a rollback. A checkpoint belongs to one session (404 from any other) and expires 30 days after it was taken or last rolled back to; expired checkpoints disappear from the list and cannot be used. Checkpoints cannot be deleted explicitly today. If the environment’s model is a Veri deployment, each session gets a model access key that can only call that deployment. It is valid for 24 hours at a time and renewed while the session is awake and when it resumes, up to 7 days after it was issued. It is revoked when the session ends or fails.

Approvals

When the agent calls a tool whose last matching permission rule is ask (or any tool under default = "ask"), the harness stops before the call runs:
  1. The transcript gets agent.approval_request {approval_id, tool_name, tool_input, tool_use_id, matched_rule, expires_at}, the session becomes awaiting_approval, the turn ends with run.completed {stop_reason: "awaiting_approval"} and the session.approval_requested webhook fires (with approval_id, tool_name and expires_at, never the tool input). The sandbox is snapshotted and stopped, so no compute is billed while you think.
  2. You answer with a user.approval event: {type: "user.approval", approval_id, decision: "allow" | "deny", message?}. 409 unless the session is awaiting_approval on that approval_id.
  3. The sandbox is restored and the agent’s turn continues. On allow the tool call runs; on deny the agent reads message as the reason and carries on without it. The turn ends with its usual run.completed.
A request that is not answered in time (the environment’s permissions.approval_ttl_s, 30 minutes by default) is denied automatically: the transcript shows user.approval {decision: "deny", reason: "timeout", by: "system"} and the turn resumes with the denial. Sending user.message while an approval is pending returns 409. One approval is open at a time. You can pause a session that is waiting for an approval. The pause denies the pending approval (the transcript shows user.approval {decision: "deny", reason: "paused", by} with your user id) and the tool call never runs. When you resume, the agent first finishes the interrupted turn: the denied call comes back to it as an error tool.result, the run completes (run.completed), and then the session is ready. Send a new message after that (ask the agent to try again if you still want the call). Checkpoint, rollback and a fork without checkpoint_id return 409 until the approval is answered or the session is paused.

Transcript

GET /v1/sessions/{id}/events?after_seq=N returns a page of events, oldest first. GET /v1/sessions/{id}/stream is a server-sent-events stream of the same rows: id is the event’s seq, event is its type. Reconnect with Last-Event-ID (or ?after_seq=) to continue without gaps; the stream closes after the session’s terminal status event. Payloads above 64 KiB (a large file read, for example) are stored in object storage; the event carries a 1 KiB preview and payload_ref. Lifecycle transitions also fire webhooks: session.started, session.approval_requested, session.paused, session.ended, session.failed.

Usage and resources

GET /v1/sessions/{id} returns a usage summary derived from the transcript (the list endpoint leaves it out) and resources, the newest sandbox sample from the heartbeat:
Token counts are recorded in two places. For a Veri-hosted model, every model call the agent makes is recorded on the deployment’s request history (GET /v1/deployments/{id}/requests) with its input, cached and output tokens, the same as any other request to that deployment, and each call carries the session id as its thread id, so monitors scoped to threads score the session’s conversation like any other thread. For your own endpoint, Veri never stores the model traffic; the per-call usage events (scope: "call") record only the token counts, model name, duration and status read off each reply, and the per-run totals the harness reports (usage with scope: "run" and run.completed.model_usage) are recorded on the transcript as well. Session token totals in the observability views follow the same rules as usage above.

Pricing and limits

A session is billed per hour while its sandbox is awake, settled per minute, at the rate of the environment’s size. The awake-time charge is rounded up to the next cent per session, once over the session’s whole life rather than per minute: any awake time costs at least $0.01, and a session never pays more than 1 cent over the exact cost of its awake time. The rate is fixed when the session is created (the API returns it as rate_usd_per_hour), so a later price change never affects a running session. Paused and ended sessions cost nothing. Model calls to a Veri deployment are billed through that deployment; calls to your own endpoint are billed by its provider. Egress is billed only in audited_open mode, at $0.025 per GB of request plus response bytes through the egress proxy (egress_bytes), settled with the session and fixed when the session is created (egress_usd_per_gb). restricted traffic is metered on the session but never billed, and unrestricted traffic is neither. Every session pauses when its egress_bytes reaches 10 GiB: the transcript records session.egress_cap_reached and failure_code reads egress_cap. Contact us to raise the cap for a workspace. Composio tool calls (coming soon) will be billed per call after a monthly free allowance, with their own per-session cap (failure_code tool_call_cap). Egress and tool calls count toward the workspace’s prepaid credit balance in real time, like awake time, before they are settled (tool calls still inside the monthly free allowance count as free): when the balance runs out, every session in the workspace stops with status failed and failure_code insufficient_credits. Set budget_usd to pause the session automatically when its awake-time spend reaches the ceiling (egress and tool calls have their own caps, above); the transcript records a session.budget_exhausted event and the session’s failure_code reads budget_exhausted. Resume it to continue (the budget still applies, so raise it first or start a new session). A workspace can have 10 sessions that are not ended at a time on the Free plan, and 25 on Pro, paused sessions and forked children included. Going over (or forking more children than fit) returns 429 CONCURRENT_SESSION_LIMIT. Contact us to raise the limit.