Skip to content
Browse the docs

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.

Updated 4 min readView as Markdown

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 nested MCP 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 agentHow you pick itSign-in
CursorPreset in the deploy wizardAPI key from a secret
Claude CodePreset in the deploy wizardWeb sign-in from chat
Kimi CLIPreset in the deploy wizardDevice sign-in, or KIMI_API_KEY
Any other ACP agentChoose from registry or Manual entryVaries 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. Agent pods ask 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 deploy falls back to Kata Containers if available, and otherwise to the default runtime. If you set a runtime class explicitly on an agent, Nested never drops it: the deploy fails with a clear error instead.

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. Operators can override them per agent.

Idle stop and wake#

Idle agents stop to free the cluster:

  1. Every minute, the deploy service checks running agents (except ones stopped by a person or open to the internet).
  2. It asks the task, formula, and knowledge services whether the agent has unfinished work. It also checks for a settings reload and for recent desktop or terminal use. Any error counts as busy.
  3. After 10 quiet minutes it checks again, then scales the agent to zero.
  4. 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?
Sysbox is the default. If the cluster lacks it, Nested falls back to Kata Containers, then to the default runtime. Install Sysbox or Kata for production isolation.