Ultron shell runtime
The Ultron shell is the per-session runtime that the chat agent runs inside: an isolated per-conversation sandbox on managed Kubernetes, running a vendored agent CLI plus a bundled toolset, fronted by a routing layer that handles auth, session state, and queue-backed async execution. Replaces the previous always-on per-user desktop sandbox.
Overview
- Runtime
- Isolated per-conversation sandbox on managed Kubernetes
- Persistence
- Durable off-instance /work snapshots, auto on every successful run
- Session key
- One sandbox instance per session id (default 'primary')
- Concurrency
- Scales automatically with active sessions
- Default backend
- Plinth (sandbox / background-agent tier)
- Alternate backend
- Forte, when the request opts into the heaviest-reasoning tier
- Fronting layer
ultron-shell
The shell is the user-facing piece of what the chat agent calls the sandbox. When a chat turn fires a tool that requires running code, fetching a page, generating a screenshot, or producing a deployable artefact, that work happens inside the shell. The chat agent never executes anything in the application runtime's own process; everything sandbox-shaped routes through the shell.
From the app's point of view
A single HTTP surface, queue-backed when needed.
The chat-v2 route in the application runtime does not know or care how the shell is implemented underneath. It sees one HTTP surface, ultron-shell.51ultron.com (or the per-tenant alias), with endpoints for exec, file IO, agent CLI invocation, and snapshot management. The session id is carried in a header; the routing layer resolves it to a session coordinator and a sandbox instance.
The session model
| Concept | Meaning |
|---|---|
| Session id | A short string the caller passes via header or query. Defaults to 'primary' when omitted. |
| Session coordinator | One coordinator per session id. Owns the sandbox handle and the session-key cache. |
| Sandbox instance | One sandbox instance per session coordinator. Owns /work and the agent CLI process. |
| Session key | Per-session HMAC-derived child key. Set on the first request and reused for sandbox -> routing-layer callbacks. |
| /work | The per-session working directory inside the sandbox. Everything the agent CLI produces during the session lives here. |
| Events log | Append-only event log in durable storage. Every job lifecycle event plus every tool invocation written here, partitioned by date. |
Snapshots and restore
A fresh sandbox instance has an empty /work. The session coordinator tracks two timestamps: startedAt (set when the sandbox boots) and restoredAt (set after a successful restore from durable storage). Before any state-touching request, the coordinator checks whether a restore is needed; if so it pulls snapshots/<session>.tar.gz from durable storage and unpacks into /work before forwarding the request to the sandbox.
Auto-snapshot fires via ctx.waitUntil after every successful agent invocation. A periodic in-sandbox snapshotter also fires every 60 seconds (configurable) to catch mid-run state, dedupes if a previous snap is still uploading, and skips when /work is empty.
node_modules can blow past that; the snapshotter excludes the npm cache and the bun cache by default, and warns when /work crosses the cap so an operator can intervene.What lives in the shell
The image is fat on purpose. Skills + binaries + a real Linux userland.
| Surface | What it gives |
|---|---|
| Agent CLI | The vendored agent CLI that drives the chosen backend. |
| Skills pack | ULTRON_OPERATING_PRINCIPLES.md and the workspace's skill set, mounted at /home/ultron/.claude/skills/. |
| /tools-bin | Shipping binaries: ultron-screenshot, ultron-deploy, ultron-render, brave-search, lookup-design-dna. |
| Node + Bun + Python | Three runtimes available. Most agent CLI work happens via Node + Bun. |
| Playwright + ffmpeg | For browser automation and media manipulation. |
| wrangler + flyctl | For deploying to the edge runtime or Fly without leaving the shell. |
| git + gh | Version control plus the GitHub CLI for repo work the agent runs autonomously. |
Inference backends
| Backend | When | Trade-off |
|---|---|---|
| Plinth (default) | Standard runs. Cheap, fast, good at code. | Slightly weaker on long-horizon reasoning than the heaviest tier. |
| Forte (override) | When the request opts into the heaviest-reasoning tier. Used for cases that need the strongest reasoning. | Higher per-token cost. |
Compared to the previous sandbox
- Always-on sandbox
- Previous sandbox kept an instance alive per user for the session duration. The shell only boots a sandbox instance on demand and lets the platform reclaim idle ones.
- Full Linux desktop with a remote view
- Previous sandbox shipped a full virtual desktop with a remote-desktop view so the user could watch it work. The shell does not expose a desktop by default; the ultron-screenshot binary covers the visual-debug case.
- User-keyed
- Previous sandbox was one instance per user. The shell is one instance per session id, so the same user can hold several sessions in parallel without contention.
- Always-up costs
- Previous sandbox billed continuously. The shell bills only when a sandbox instance is running.
- Snapshot model
- Previous sandbox kept /home/user on a persistent volume. The shell snapshots /work to durable storage on every successful run; idle sessions can be reclaimed and rehydrated transparently on the next request.