Install Nested
Install a Nested cell on your Kubernetes with nested-install: requirements, the setup file, the install steps, upgrades, backups, and teardown.
How installation works#
nested-install is a command-line tool that installs one Nested cell from one setup file. It runs on your machine, talks to your cluster through a kubeconfig, and keeps its state in a state folder beside the setup file.
Each install runs as a resumable workflow: every step is recorded, and an interrupted install continues from the first unfinished step. Generated secrets are read from the state folder, so they never appear in workflow history.
Before you start#
- A Kubernetes cluster and a kubeconfig with admin rights to it.
- A default StorageClass (or one you name in the setup file).
- A DNS zone. Public hosts are derived from the cell slug and zone, for example
acme.example.com. - Optional: Sysbox or Kata Containers for agent isolation. The installer can install either.
Steps#
- Write a commented setup file:
nested-install init- Edit
setup.yaml. At minimum, setkubeconfig,cell.slug, andcell.zone:
kubeconfig: ~/.kube/config
cell:
slug: acme
zone: example.com
display_name: Acme
cluster:
runtime: sysbox # sysbox, kata, or none
services:
ntfy: true
observability: false
argocd: true # false stops after the platform layer- Create the cell:
nested-install bootstrap --file setup.yaml- If the run stops, check it and continue:
nested-install status --file setup.yaml
nested-install resume --file setup.yamlWhat the installer creates#
- Namespaces:
platform,apps, andagent-platform. - Platform charts: the CloudNativePG operator, Traefik when ingress is managed, cert-manager when enabled, and the platform services — Postgres, Dragonfly, Temporal, NATS, RustFS, and optionally ntfy and observability.
- A database and role for each Nested service.
- With
services.argocd: true: the server configuration, the Nested apps registered as Argo CD applications, the default authorization policies, and your cluster registered with its first agent in the catalog.
The data services and Temporal are required; the installer refuses a setup file that turns them off.
Setup file reference#
| Block | What it sets |
|---|---|
cell | Slug, DNS zone, scheme, display name, and optional custom origins for the app, console, and API |
namespaces | Platform and app namespaces |
cluster | Cluster name, agent namespace, ingress class, StorageClass, and sandbox runtime |
agents | The agent catalog: image and the coding agents each one installs |
services | Optional services: ntfy, observability, auth proxy, Argo CD, cert-manager |
images | Image repositories and tags for the apps |
ingress | Hosts for the API, app, console, webhooks, notifications, and object storage |
environments | Turns on the Environments service; requires Argo CD and cert-manager |
Day-two operations#
| Task | Command |
|---|---|
| Re-apply after changing the setup file | nested-install apply --file setup.yaml |
| Roll the apps to the current image digests | nested-install update --file setup.yaml |
| Converge only the platform charts | nested-install platform apply --file setup.yaml |
| Back up the setup file and state | nested-install export --file setup.yaml |
| Restore from a backup | nested-install import <archive> |
| Remove the cell | nested-install destroy --file setup.yaml |
After the install, sign in to the console to configure official connectors and the agent catalog, then open the app and deploy your first agent.
Questions
- How do I install Nested?
- Run
nested-install initto write a setup file, fill in your kubeconfig, cell slug, and DNS zone, then runnested-install bootstrap --file setup.yaml. - What happens if the install fails halfway?
- Every step is recorded in the state folder. Fix the cause and run
nested-install resume; it continues from the first unfinished step. - Do I need Argo CD?
- Argo CD is how the installer rolls out the Nested apps. With
services.argocd: false, the installer stops after the platform layer.