Sessions: picking up where you left off¶

A session is a stream of work you can come back to, like a cloud Claude session: the agent's conversation and the repo state are kept; the sandbox is not. Design: spec 0010.

# Monday
hangar session new onboarding "build the onboarding flow; start with the signup form" -e early-signal -w
hangar session send onboarding "use the existing Button component" -w

# ...30 idle minutes later hangar checkpoints it and releases the sandbox (costs storage only)...

# Wednesday
hangar session list
hangar session send onboarding "now add the email verification step" -w   # boots, restores, resumes the conversation

What is kept¶

Checkpoints are taken:

• after every agent turn;
• every 10 minutes while something changes;
• when the session suspends;
• before its sandbox is destroyed for any reason, including expiry.

Checkpoints are encrypted with the vault key.

All four agents resume their own conversation: Claude Code, Codex, pi and Antigravity (agy --conversation <id>). If you switch a session to a different agent, the next prompt starts with a short account of the earlier turns instead (a handoff).

Staying open while you work¶

A session never suspends while it's in use. Any of these keeps it up:

• an agent turn running, or any agent run started in its sandbox (run_agent) that hasn't finished;
• a terminal open on it (dashboard or hangar sb attach);
• anything using the sandbox through hangar: commands (for their whole run), files, reading terminals, following an agent.

A job's session is held for the whole turn, delivery included, and across a control-plane restart until the job picks it up again.

It suspends only after it has been idle for its idle time: 30 minutes by default. To change that:

hangar session keep onboarding --idle 240   # four hours
hangar session keep onboarding --idle 0     # stay up until I suspend it

Commands¶

hangar session new takes a per-turn budget (--max-cost, --max-tokens, --max-minutes; budget in the API). A turn that crosses it is stopped with outcome over_budget. get shows each turn's usage and the session's total.

If the agent asks a question (hangar-agent ask), the turn ends as needs_input and the session shows it in needs_input; your next send answers it. How context moves in and out of a session is in context exchange.

In the dashboard, the Sessions page does all of this:

• Resume a session;
• message the agent;
• Talk to the agent here, which opens a terminal in the agent's own conversation;
• open a shell;
• set the idle time.

To work alongside the agent interactively from a terminal:

1. Open the session and attach to its sandbox: hangar sb attach <sandbox_id>.
2. Run the resume_command that get shows, for example claude --resume 3f2a…. You're now in the same conversation the agent had.

Thawed from a harness lock¶

hangar harness thaw team-default@r14 --env python "fix the flaky test" (or harness_lock on POST /api/sessions) starts a session from a harness lock: the lock's harness, its concrete model and its approval mode, on the CLI version harnesses.lock.yaml pins (a lock on another version is refused, with what to do). Its turn 1 is checked against the lock; SessionTurn.drift lists what differed ([]: nothing), with a harness.drift event and a warning on the turn. Under HANGAR_HARNESS_DRIFT=fail turn 1 stops with outcome failed, reason harness_drift. Later turns aren't checked: what the agent changes is its behaviour. A thawed session can't switch harness; start another session for another lock.

Settings¶

Cost and speed¶

• Suspended session: a few MB on the control plane's volume.
• Resume: a sandbox start plus the restore (seconds for typical sizes). That's about 10 s from a warm pool, or 30–60 s cold when the image is built and a node is up.
• Keeping a sandbox running overnight instead: it pins a sandbox node, roughly $280/month on demand for an n2-standard-8.
• Faster cold starts on GKE (opt-in, recreates the sandbox nodes): terraform image_streaming = true starts pods before the image is fully pulled, and sandbox_disk_gb = 100 lets more nodes fit the default 500 GB SSD quota. Suspend sessions before applying; they resume from their checkpoints.
• Durability: with HANGAR_SESSION_STORE=gs://…, checkpoints survive the control plane's disk. Uploads retry on throttling and server errors. The bucket has no age-based deletion unless you set session_retention_days.

Moved from this page¶