Skip to content

Inside cloud-agent: how a Nested agent runs, sleeps, and recovers

What runs in each agent pod: ACP sessions with Cursor, Claude Code, or Kimi, the sandbox, idle scale-to-zero, crash recovery, and drain-and-restart reloads.

6 min read

A pod that hosts a coding agent#

Every agent you deploy in Nested is one Kubernetes pod running cloud-agent. It is not itself a model or a coding agent. It is the host that turns a vendor coding agent — Cursor, Claude Code, Kimi, or another — into a durable, multi-task worker that lives in your cluster.

The pod has a lot to juggle: claiming tasks from the platform, keeping several coding sessions alive, holding vendor logins, staying inside a sandbox, going to sleep when nobody needs it, and picking up exactly where it left off after a crash. This post is a tour of how each of those works.

What is in the image#

The agent image comes in two flavors: a full Ubuntu desktop with Chrome (so you can watch the agent’s screen from the app) and a lighter variant without a desktop. Both ship the cloud-agent binary, an SSH server, Node.js, and a few context-saving command-line tools.

What the image does not contain is any vendor’s coding-agent CLI. On startup, the agent installs the coding agent you chose from the public Agent Client Protocol registry. That keeps the image vendor-neutral and lets each agent update its CLI without us rebuilding anything. Docker, Ollama, and similar tools arrive as packs, not as image layers.

Talking to coding agents over ACP#

cloud-agent drives coding agents through the Agent Client Protocol (ACP): JSON-RPC over the coding agent’s standard input and output. The app offers three presets — Cursor, Claude Code, and Kimi — and any other agent in the ACP registry can be configured by hand.

Signing in#

Coding agents need their vendor’s login. The agent supports API keys from a bound secret and, for agents that support it, a headless sign-in: the app shows you a URL or device code, you approve it, and the agent finishes the login. While sign-in is needed, the agent holds new work for that vendor and the app shows Sign in to use this agent. A login attempt expires after 15 minutes.

One agent can hold up to 10 vendor accounts and switch between them. Switches are crash-safe: credentials are written to a temporary file and renamed, and a journal lets a restarted pod roll back a switch that did not commit. A normal switch waits up to 10 minutes for running turns to finish; a forced switch gives them 30 seconds.

Sessions#

Live coding sessions are keyed by context, task, and agent. Two tasks in the same conversation context get independent coding sessions but share the context’s workspace directory, so one task can pick up the files another left behind. A pooled session is closed after 30 idle minutes — unless it still has background work, such as a subagent, a pending permission prompt, or an open terminal.

The worker claims new tasks every five seconds and runs up to four turns in parallel. A turn may run for up to 24 hours.

The sandbox#

The first isolation boundary is the pod. By default it runs under the Sysbox runtime in a user namespace, which lets the agent run its own Docker daemon without a privileged container. If Sysbox is not available, deploy falls back to Kata microVMs, then to the default runtime — unless you pinned a runtime, in which case the deploy fails rather than downgrade.

Inside the pod, the coding agent, its terminals, and hook scripts run with a deny-by-default environment. Only an allowlist of variables passes through, and names that look like credentials (*_TOKEN, *_SECRET, *_PASSWORD, AWS_*, DATABASE_*, KUBERNETES_*) are always stripped.

We tried a per-process filesystem sandbox with bubblewrap first. It does not work inside Sysbox, because nested user namespaces fail there, so the pod boundary stays the filesystem boundary.

Sleeping when idle#

An agent that nobody is using still holds CPU and memory. So the deploy service stops idle agents:

  1. Every minute, under a database lock so only one control-plane replica acts, it looks at running agents that a person did not stop.
  2. For each one, it asks: does the task service have unfinished work for it? Does the formula service have unfinished runs? Is a memory reorganize using it? Is a settings reload in progress? Was there recent terminal or desktop activity?
  3. Any error counts as busy. We would rather keep an agent up for nothing than stop one mid-task because a probe timed out.
  4. After 10 quiet minutes, it records the stop reason as idle, probes once more, and scales the agent to zero.

When new work arrives — a message, an automation, a formula step — the task service asks the deploy service to start the agent again, and the task waits as submitted until the agent claims it. Workspaces live on persistent volumes, so nothing is lost. If you stopped an agent yourself, it stays stopped; idle wake never overrides a person.

Recovering a turn after a crash#

Pods restart: a node drains, a container runs out of memory, an image updates. Each agent is a single pod, which makes recovery simple. On boot, the agent looks for tasks that were WORKING before this process started, and tasks that were waiting on background work. Any such task was interrupted by definition — no other process could have been running it. No heartbeat or lease needed.

For each one, it asks the task service to continue it. In one transaction, the task service appends a system continuation message and requeues the task, and the normal worker picks it up — the same path as you typing “continue”.

Automatic recovery is capped at three attempts per task per hour. After that, the agent stops and tells you: “The agent restarted several times while working on this task, so it stopped resuming automatically. Send a message to continue.” A crash loop should not burn your model budget overnight.

Changing settings without killing work#

Agent settings changes are applied by draining and restarting, not by swapping config inside a running process:

  1. The deploy service tells the agent, over a loopback-only control port reached through a port-forward and authenticated with a per-agent token, that a new configuration exists.
  2. The agent stops admitting new work and waits for running turns. It never cancels them.
  3. The process exits; Kubernetes restarts the container.
  4. On boot, the agent fetches the desired configuration. Each configuration has a generation — a keyed HMAC fingerprint of its content — so the agent knows whether it is current.

If running turns do not finish within five minutes, the agent stays on the old configuration, reports a drain timeout, and opens up again. An unparseable configuration crashes the boot on purpose, so a bad save is loud instead of half-applied. Image, resource, and storage changes still need a full redeploy.

What you see in the app#

SituationWhat the app shows
Agent stopped while idle“It stopped after a quiet period to free resources,” with Start agent — or it starts when you send work
Vendor sign-in neededA sign-in prompt with a link or code
Pod restarted mid-turnThe task resumes on its own, up to three times an hour
Settings savedRunning turns finish before the agent restarts with the new settings
Checking the agent’s machineDesktop and Terminal from the task panel

Trade-offs#

  • One pod per agent. There is no failover replica. A singleton keeps recovery and workspace ownership simple; the cost is a short gap while a pod restarts.
  • No liveness probe. A coding turn can look idle from outside for a long time. We accept slower detection of a truly hung process to avoid killing real work.
  • Cold starts. An idle-stopped agent takes time to start again, so the first task after a quiet period waits for the pod. We chose lower idle cost over instant answers.

Closing#

The goal of cloud-agent is to make a coding agent behave like a dependable service: it accepts work from a queue, survives restarts, sleeps when it can, and never drops a turn silently. For the setup side, see Deploy an agent and Agent settings.

Last revised .

Questions

Which coding agents does Nested support?
Cursor, Claude Code, and Kimi are presets in the app. Other agents from the Agent Client Protocol registry can be configured manually.
Do idle agents keep running and using resources?
No. After about 10 quiet minutes with no tasks, formula runs, or recent terminal activity, an agent scales to zero. It starts again when new work arrives, with its workspace intact.
What happens to a running task if the agent pod restarts?
The agent finds interrupted tasks on boot and continues them automatically, up to three times per task per hour.
Does changing agent settings interrupt running tasks?
No. The agent drains running turns before restarting with the new settings. If they do not finish within five minutes, it keeps the old settings and reports a timeout.

6 min read

The Nested security model, layer by layer

Sign-in, tokens, teams, secrets at rest, site logins, agent sandboxes, and audit: how Nested protects an install, and the gaps we have not closed yet.