Why Nested runs inside your Kubernetes cluster
Coding agents need your repos, tokens, and prompts. Here is what Nested installs in your cluster, where each piece of data lives, and the trade-offs.
7 min read
The question every security review asks#
A coding agent is only useful when it can touch real things: your repositories, your issue tracker, your CI logs, the credentials for the services it debugs. That is exactly the material a security team does not want copied into somebody else’s multi-tenant database.
So the first design decision in Nested was not about models or prompts. It was about where the platform runs. Our answer: the whole platform — control plane, agent runtime, and the data services behind them — installs into a Kubernetes cluster that you operate. One install is one isolated unit. There is no shared Nested backend that every customer talks to.
This post walks through what actually lands in your cluster, how an agent gets deployed, where each kind of data ends up, and what you give up by running it yourself.
Three layers in one cluster#
A Nested install has three layers, and each one has a single owner.
| Layer | What it contains | Who installs and updates it |
|---|---|---|
| Platform services | Postgres, a Redis-protocol cache, Temporal, NATS, an S3-compatible object store, and optional extras | The nested-install CLI, through Helm |
| Apps | The control plane (server), the Nested app, the operator console | The installer, optionally handed to Argo CD |
| Agent deployments | One cloud-agent pod per agent | The control plane, at runtime, through an embedded Helm chart |
Keeping these owners separate is deliberate. Helm owns the shape of the platform. The control plane owns agents. Nobody edits the same object from two directions, which is what usually breaks upgrades.
The platform services#
Every install gets the same core services, and the installer requires all of them. The control plane depends on each one except NATS, which is installed for future use.
| Service | What Nested uses it for |
|---|---|
| Postgres (CloudNativePG operator) | One database per feature — tasks, deployments, knowledge, packs, automations, auth, and the rest. Temporal gets its own databases too. |
| Dragonfly (Redis protocol) | Short-lived state: OAuth state and consent transactions, token-revocation lookups, caches. |
| Temporal | Durable workflows: agent turns, formula runs, automation schedules, scheduled tasks, pack builds, and report generation. |
| S3-compatible object store (RustFS) | Knowledge page bodies, task attachments, runbooks, pack archives, and reports. |
| NATS | Installed and secured with an auth callout, but not yet an active data path. It is provisioned for future fleet messaging. |
Then there are toggles: ntfy for push notifications, an OpenTelemetry collector with Jaeger and Grafana for traces and metrics, an auth proxy in front of platform UIs, cert-manager, and Argo CD with its image updater.
The apps#
The control plane is a single server binary built from feature modules: auth, deploy, task, formula, knowledge, pack, hook, automation, report, notification, discovery, MCP connectors, site access, environments, and a few more. Each module owns its own Postgres database. The Nested app (where people talk to agents) and the operator console are separate web apps that call it.
The installer is a workflow, not a script#
Installing a stateful platform is a long sequence of steps, and long sequences fail halfway. nested-install treats installation as a durable workflow:
- It loads and validates one
setup.yamland takes a file lock on its state directory. - It starts a private Temporal dev server on loopback, backed by a SQLite file in the state directory.
- It runs one workflow per command: preflight checks, namespaces, secrets, the Helm releases, waiting for the platform, rendering server configuration, and registering the apps.
- It records each finished step. If the run dies,
nested-install resumecontinues from the first unfinished step.
Two details matter for security. Generated secrets are written to a file in the state directory and read from disk by each step, so they never enter workflow history. And the installer writes a single values file that every Helm release reads, so there is one place to review what was configured.
The installer creates three namespaces by default: one for platform services, one for the apps, and one for agent pods.
How an agent becomes a pod#
When someone deploys an agent from the app, the control plane’s deploy module does the following:
- Merges configuration in three layers — chart defaults, then the agent template, then this deployment’s overrides. Sensitive values go into a Kubernetes Secret; the rest into a ConfigMap.
- Renders the user’s bound secrets into a chart-owned Secret and wires each one into the pod with
secretKeyRef, so values never appear inline in the manifest. - Picks a container runtime. The default RuntimeClass is
sysbox-runc, which gives each agent a user-namespaced pod that can run its own Docker daemon. If your cluster does not have Sysbox, deploy falls back to Kata, then to the default runtime — unless you set a RuntimeClass explicitly, in which case a missing one fails the deploy instead of silently downgrading. - Runs
helm upgrade --install --waitand keeps reconciling: a loop reads release and pod status every minute and records what it saw.
The pod itself is a singleton Deployment (one replica, or zero when stopped) with a Recreate strategy. It has two persistent volumes, one for data and git workspaces and one for Docker’s image store, and both survive an uninstall. Undeploy and redeploy an agent and its workspaces are still there.
Where your data lives#
Here is the honest map of what is stored where.
| Data | Where it lives |
|---|---|
| Prompts, messages, task history | Postgres in your cluster |
| Runbooks (each turn’s tool calls, plan, output) | Object store in your cluster, indexed in Postgres |
| Memories and knowledge centers | Postgres (index, versions) and object store (page bodies) in your cluster |
| Connector OAuth tokens | Encrypted at rest (AES-256-GCM) in the connectors database in your cluster |
| Your secrets for agents | Encrypted in Postgres, delivered to pods as Kubernetes Secrets |
| Git workspaces | The agent’s persistent volume in your cluster |
Some traffic does leave the cluster, and we want to be exact about it. The coding agent inside each pod — Cursor, Claude Code, Kimi, or another ACP-compatible agent — talks to its own model provider with the account you signed it in with. Connectors call the services you connected. At startup, an agent downloads its coding-agent CLI from the public Agent Client Protocol registry. The control plane’s built-in assistant calls the OpenAI-compatible LLM endpoint you configure at install, and formula gates that ask typed questions send the question and its evidence to that same endpoint — or to an external gate-resolver service, but only if an operator sets that service’s API key. Nested itself does not keep a copy of your prompts, code, or tokens on vendor infrastructure.
One feature is an explicit exception. Environments — short-lived machines that agents use to run and test an app — are cloud VMs (DigitalOcean today), not pods in your cluster. The Environments service that manages them runs in your cluster, the VMs accept no inbound traffic, and they reach the service only through an outbound tunnel. But the code and secrets you send to an environment do run on that VM. Environments are off per team until an operator turns them on.
What you give up#
Running inside your cluster is not free. You should know the costs before you choose it.
- You operate it. Backups, upgrades, capacity, and the cluster itself are yours. The installer makes upgrades repeatable, but it does not make them disappear.
- No shared fleet. Each install is its own cell with its own server and its own Postgres. There is no cross-customer manager, which is the point, but it also means there is no central place we can fix things for you.
- Agents need real resources. The default pod requests 250m CPU and 3 GiB of memory, with limits of 4 CPUs and 6 GiB. Agents that sit idle stop on their own after a quiet period (we cover that in Inside cloud-agent), but busy agents cost what busy development machines cost.
- Model calls still leave. Your data boundary is the cluster plus the model provider you choose. If that is not acceptable, pick an agent and provider that you can run privately.
Why not a SaaS with good contracts?#
We considered it. A hosted platform is easier to start and easier for us to operate. But a coding agent accumulates exactly the context a company guards most: how its systems fail, where its credentials are used, what its unreleased code does. Contracts describe what a vendor promises to do with that data. Running in your cluster means the vendor never has it.
Closing#
The rest of Nested follows from this choice: agents are pods you can see with kubectl, durable work rides on the Temporal you host, and every credential is encrypted with keys in your configuration. If you want the step-by-step view, start with What is Nested and the architecture docs.
Last revised .
Questions
- Is Nested a multi-tenant SaaS?
- No. Each install runs in one Kubernetes cluster that you operate, with its own control plane, Postgres, and object store. There is no shared Nested backend.
- Do my prompts leave the cluster?
- Prompts and task history are stored in your cluster. The coding agent in each pod sends prompts to the model provider you signed it in with, so your boundary is the cluster plus that provider, and any other service you configure, such as the install’s LLM endpoint or an opt-in gate resolver.
- What does Nested install into my cluster?
- Postgres (CloudNativePG), a Redis-protocol cache, Temporal, NATS, an S3-compatible object store, the control plane and web apps, plus one pod per agent you deploy.
- Can an agent keep its workspace after it is undeployed?
- Yes. Each agent has persistent volumes for data and Docker images that are retained on uninstall and adopted again on the next deploy.
More from the blog
6 min read
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
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.
6 min read
Agents talking to agents: tasks, A2A, and discovery in Nested
Every request to an agent is a task in one system of record. How Nested uses the A2A model for delegation, discovery, lineage, and who closes a task.