Skip to content
Browse the docs

Install Nested

Install a Nested cell on your Kubernetes with nested-install: requirements, the setup file, the install steps, upgrades, backups, and teardown.

Updated 3 min readView as Markdown

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#

  1. Write a commented setup file:
bash
nested-install init
  1. Edit setup.yaml. At minimum, set kubeconfig, cell.slug, and cell.zone:
yaml
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
  1. Create the cell:
bash
nested-install bootstrap --file setup.yaml
  1. If the run stops, check it and continue:
bash
nested-install status --file setup.yaml
nested-install resume --file setup.yaml

What the installer creates#

  1. Namespaces: platform, apps, and agent-platform.
  2. 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.
  3. A database and role for each Nested service.
  4. 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#

BlockWhat it sets
cellSlug, DNS zone, scheme, display name, and optional custom origins for the app, console, and API
namespacesPlatform and app namespaces
clusterCluster name, agent namespace, ingress class, StorageClass, and sandbox runtime
agentsThe agent catalog: image and the coding agents each one installs
servicesOptional services: ntfy, observability, auth proxy, Argo CD, cert-manager
imagesImage repositories and tags for the apps
ingressHosts for the API, app, console, webhooks, notifications, and object storage
environmentsTurns on the Environments service; requires Argo CD and cert-manager

Day-two operations#

TaskCommand
Re-apply after changing the setup filenested-install apply --file setup.yaml
Roll the apps to the current image digestsnested-install update --file setup.yaml
Converge only the platform chartsnested-install platform apply --file setup.yaml
Back up the setup file and statenested-install export --file setup.yaml
Restore from a backupnested-install import <archive>
Remove the cellnested-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 init to write a setup file, fill in your kubeconfig, cell slug, and DNS zone, then run nested-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.