# Architecture

> What Nested installs into your Kubernetes cluster — control plane, agent pods, and platform services — and how a task flows through them.

Section: Platform · Updated: 2026-11-19 · Canonical: https://nested.me/docs/architecture

## 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](https://nested.me/docs/chat).
- **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](https://nested.me/docs/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

1. A person sends a message in the app. The control plane’s task service stores a new task in Postgres in the `SUBMITTED` state.
2. 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.
3. The agent pod polls the task service and atomically claims the oldest submitted task for its deployment. The task moves to `WORKING`.
4. 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.
5. Progress streams back as task events. A runbook — prompt, tool calls, plan, output, usage — is written to object storage.
6. 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](https://nested.me/docs/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](https://nested.me/docs/environments-platform), those machines run on a cloud provider, outside your cluster.

> [!NOTE]
> The privacy policy covers the vendor’s side of this. See the [Privacy policy](https://nested.me/privacy).

## 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](https://nested.me/docs/install).

## Related

- [Agent runtime](https://nested.me/docs/agent-runtime)
- [Security model](https://nested.me/docs/security)
- [Install Nested](https://nested.me/docs/install)
- [Tasks and agent collaboration](https://nested.me/docs/agent-collaboration)
