Agent runtime
How a Nested agent pod works: coding agents over ACP, task sessions, the sandbox, idle stop and wake, crash recovery, and settings reloads.
What runs in an agent pod#
Every agent is one pod running cloud-agent. The process does four jobs:
- Claims tasks for its deployment from the control plane’s task service.
- Drives one or more coding-agent CLIs over the Agent Client Protocol (ACP), a JSON-RPC protocol over stdio.
- Loads the agent’s packs: skills, subagents, formulas, MCP servers, and setup scripts. See Packs.
- Serves the built-in
nestedMCP server that gives the coding agent platform tools. See MCP servers and connectors.
The image comes in two variants: a full Ubuntu desktop with Chrome, which powers the agent’s desktop, and a lighter Ubuntu image without it. Docker inside the pod comes from a pack, not the base image.
Supported coding agents#
The image ships no vendor CLI. When the agent starts, it installs the coding agents it is configured with from the public ACP registry. You can also point it at a command that is already installed.
| Coding agent | How you pick it | Sign-in |
|---|---|---|
| Cursor | Preset in the deploy wizard | API key from a secret |
| Claude Code | Preset in the deploy wizard | Web sign-in from chat |
| Kimi CLI | Preset in the deploy wizard | Device sign-in, or KIMI_API_KEY |
| Any other ACP agent | Choose from registry or Manual entry | Varies by agent |
Among the registry agents, OpenAI Codex has a headless sign-in path, but it has no preset in the deploy wizard. Gemini requires you to sign in from the agent’s desktop.
Sign-in and multiple accounts#
When a coding agent needs a login, the agent holds new work and shows a sign-in prompt in chat. Logins run headless: you get a URL or a device code and finish in your browser. An attempt expires after 15 minutes.
One agent can keep up to 10 vendor accounts and switch between them. A normal switch waits up to 10 minutes for running turns to finish. A forced switch gives cancelled turns 30 seconds. Switches are journaled, so a crash mid-switch rolls back instead of leaving credentials half moved.
Tasks, turns, and sessions#
- The agent polls for work every 5 seconds and runs up to 4 turns in parallel by default.
- One turn may run for up to 24 hours, with a 10-minute heartbeat timeout.
- Each task gets its own coding-agent session. Tasks in the same workspace share one working directory, but not one conversation.
- A pooled session closes after 30 minutes idle — unless it still has background work: a running subagent, a pending permission request, or an open terminal.
The sandbox#
Isolation starts at the pod boundary. Each agent has a runtime, chosen when it is created and fixed afterwards:
- Standard (the default). The pod asks for the Sysbox runtime and a user-namespaced pod (
hostUsers: false), so the agent can run Docker without being privileged on the node. If the cluster has no Sysbox, the pod uses the default container runtime. There is no automatic fallback to Kata. If an operator sets a runtime class explicitly on an agent, Nested never drops it: the deploy fails with a clear error instead. - Isolated VM (Kata). The pod runs in its own lightweight virtual machine under the
nested-kataruntime class. The person creating the agent opts in; the choice is offered only when the cluster has Kata. If Kata is missing at deploy time, the deploy fails rather than run with weaker isolation. A Kata agent reserves its full memory limit, keeps its volumes as raw block devices, and starts and builds more slowly.
Nested strips privileged mode from every agent pod that is not a Kata pod.
Where agent pods run#
On a cluster with node roles, agent pods prefer nodes labeled nested.io/agents=true and never run on a node labeled nested.io/platform=true unless it also has the agents label. Clusters without role labels schedule agents on any node.
Inside the pod, coding-agent processes, their terminals, and hook scripts get a deny-by-default environment. They see a short allow list (PATH, HOME, LANG, TERM, and a few others). Variables matching *_SECRET, *_TOKEN, *_PASSWORD, DATABASE_*, AWS_*, and KUBERNETES_* are removed. Startup tasks run without this filter.
Pods run as an unprivileged user (uid 1000). Default resources are requests of 250m CPU and 3 GiB memory, with limits of 4 CPU and 6 GiB; a Kata agent requests its full memory limit. Operators can override them per agent.
Idle stop and wake#
Idle agents stop to free the cluster:
- Every minute, the deploy service checks running agents (except ones stopped by a person or open to the internet).
- It asks the task, formula, and knowledge services whether the agent has unfinished work. It also checks for a settings reload, for recent desktop, terminal, or sign-in activity, and for a rollout within the last quiet period. Any error counts as busy.
- After 10 quiet minutes it checks again, then scales the agent to zero.
- New work starts the agent again automatically. Volumes are kept, so the workspace is where you left it.
An agent that a person stopped stays stopped. In the app, a stopped agent shows Start agent. See Agent settings.
Crash recovery#
A deployment has exactly one pod, so on startup the agent knows that any task still marked WORKING from before its boot died with the old process. For each one, it appends a system “continue” message and requeues the task — the same path as you typing “continue”. Recovery runs at most 3 times per task per hour. After that, the task says it stopped resuming and waits for you.
Settings changes#
Saving agent settings does not swap config in place. The agent stops taking new turns, waits up to 5 minutes for running turns to finish, then restarts on the new settings. If turns are still running at the deadline, it stays on the old settings and reports the timeout. Changes to the image, resources, or databases need a redeploy instead.
Usage and health#
The agent records usage events — tokens, skills used, and similar — in its own database and keeps them for 90 days. It reports live CPU and memory (sampled from cgroup v2) to the control plane every 30 seconds. The console shows both.
Questions
- Which coding agents does Nested support?
- The deploy wizard has presets for Cursor, Claude Code, and Kimi CLI. You can also add any agent from the public Agent Client Protocol registry or a command you install yourself.
- Do idle agents keep using resources?
- No. After about 10 minutes with no work, an agent scales to zero. It starts again when new work arrives, and its volumes keep the workspace.
- What happens if an agent pod restarts during a task?
- The agent resumes the interrupted task automatically when it boots, up to 3 times per task per hour.
- Are agent pods always sandboxed with Sysbox?
- Standard agents use Sysbox when the cluster has it, and the default container runtime otherwise. An agent created with the Isolated VM runtime runs in its own Kata virtual machine instead.