Architecture
What Nested installs into your Kubernetes cluster — control plane, agent pods, and platform services — and how a task flows through them.
One install per cluster#
Nested is not a multi-tenant SaaS. Each install — a cell — lives in one Kubernetes cluster that you operate: one control plane, one Postgres, one set of agents. Isolation between customers is the install itself, not a tenancy layer in a shared service.
A cell has three layers:
| Layer | What runs there | Who installs it |
|---|---|---|
| Platform services | Postgres, Redis-compatible cache, Temporal, object storage, push notifications, optional observability | nested-install with Helm |
| Apps | The control plane (server), the operator console, the Nested app, and optionally this site | nested-install, optionally through Argo CD |
| Agent deployments | One cloud-agent pod per agent | The control plane, at runtime, with an embedded Helm chart |
By default the installer creates three namespaces: platform for data services, apps for the Nested apps, and agent-platform for agent pods.
The three surfaces#
- The app — where people work: tasks, automations, memories, connectors. See Chat and tasks.
- The console — where operators register clusters, manage the agent catalog and packs, and configure official connectors.
- The runtime — agent pods that do the work. See Agent runtime.
Platform services#
| Service | What Nested uses it for |
|---|---|
| Postgres (CloudNativePG operator) | System of record. Each platform feature — tasks, formulas, knowledge, packs, automations, auth, and the rest — has its own database. |
| Dragonfly (Redis protocol) | Short-lived state: OAuth and consent transactions, refresh-token reuse detection, caches. |
| Temporal | Durable workflows: agent turns, formula runs, automation and schedule firings, memory distillation, and pack builds. |
| RustFS (S3-compatible) | Objects: knowledge pages, task attachments and shared files, runbooks, pack archives. |
| ntfy | Push notification delivery to browsers and phones. Optional. |
| OpenTelemetry, Jaeger, Grafana | Traces and metrics. Optional, off by default. |
| oauth2-proxy | Sign-in in front of internal tools. Optional, off by default. |
| Argo CD | Rolls out the Nested apps when you turn it on. Optional. |
The installer also installs NATS, secured behind Nested auth. Nothing in the product uses it as a data path today.
How a task flows#
- A person sends a message in the app. The control plane’s task service stores a new task in Postgres in the
SUBMITTEDstate. - The task service checks that the sender may give work to that agent. If the agent has stopped for being idle, the task service asks the deploy service to start it.
- The agent pod polls the task service and atomically claims the oldest submitted task for its deployment. The task moves to
WORKING. - The agent runs the turn as a durable workflow. It drives a coding agent (for example Cursor or Claude Code) over the Agent Client Protocol, with your packs, connectors, and memories attached.
- Progress streams back as task events. A runbook — prompt, tool calls, plan, output, usage — is written to object storage.
- When the coding agent finishes its turn, the task waits for you in Needs you. You reply, mark it done, or abort it.
Agent-to-agent work — handing a peer a task — goes through the same task service, so it is stored, authorized, and visible like any other task. One exception: when an agent downloads a file from a peer, it calls that peer agent’s API directly, at the address discovery reports. See Agent collaboration.
How agents are deployed#
The control plane installs each agent with helm upgrade --install against the target cluster. It renders settings in three layers — chart defaults, the agent template, then per-deployment overrides — and puts sensitive values in a Kubernetes Secret, not a ConfigMap. Deploys run inside the control plane process, guarded by a generation number so an older deploy cannot overwrite a newer one. A reconcile loop reads release and pod status every minute.
Each agent is a singleton: one pod, Recreate strategy, and two persistent volumes (data and Docker storage, 20 GiB each by default). The volumes are kept when the agent is undeployed, so redeploying the same agent keeps its git workspaces.
What stays in your cluster#
Task history, messages, runbooks, memories and knowledge, pack archives, secrets, and connector tokens are stored in the Postgres and object storage inside your cluster. The vendor does not receive a copy.
Some traffic leaves the cluster. Each flow below exists because you configured or enabled something:
- The coding agent you pick calls its own model provider, under your account with that provider.
- The control plane’s built-in assistant calls the OpenAI-compatible LLM endpoint you configure at install. The installer requires one.
- Formula gates that ask typed questions send the question and the gate’s evidence to a resolver. An external gate-resolver service is used only when an operator sets its API key at install; without a key, the gate falls back to the LLM endpoint above when the gate allows a fallback.
- Connectors call the services you connect (GitHub, Slack, Google, and others).
- At startup, agents download coding-agent CLIs from the public ACP registry, unless you configure a local install.
- If your team uses Environments, those machines run on a cloud provider, outside your cluster.
Questions
- Is Nested a SaaS?
- No. Every Nested service — control plane, agents, and data stores — installs into a Kubernetes cluster you operate. Each install serves one organization.
- Does Nested store my code or prompts on vendor servers?
- No. Tasks, runbooks, memories, and connector tokens live in the Postgres and object storage inside your cluster. The coding agent you choose still sends prompts to its own model provider under your account.
- What does Nested need from my cluster?
- A Kubernetes cluster with a default StorageClass, an ingress, and a DNS zone for the Nested hosts. Sysbox or Kata is recommended for agent isolation. See Install Nested.