Deploy with your AI agent
Let Claude Code, Codex or another coding agent size, install, verify and operate nano Self-run on your hosts with the nano-deploy agent skill.
nano-deploy is an official nano agent skill for coding agents
such as Claude Code and Codex. It walks your agent through a nano Self-run
deployment on your own hosts:
- Intake. It asks for your hosts, SSH access, topology, volume and retention, hostnames and TLS, and where your bundle, registry credential and enrollment values are saved.
- Sizing. It sizes the hosts from your EPS or GB/day and retention, using the sizing guide.
- Read-only preflight over SSH. It checks the OS, CPU and AVX2, memory,
disk, Docker and Compose, time sync, ports and connectivity between nodes.
It stops on any failed check. After the install,
preflight.sh --exposure-probe <server addresses>, run from a machine outside the cluster, warns about any database or cluster port that answers; see Host firewall. - Deploy. Single node, 3-node HA (Compose role split, with ingest kept off the app host), a cluster of several VMs with no single point of failure, or Kubernetes with Helm. It follows the Self-run order (prepare, add enrollment values, install) and shows you each step before it runs it.
- Verify. It checks health, admin login and license state, ingests a marked test event and finds it with search, and on HA checks Keeper quorum and ClickHouse replica health.
- Day 2. Upgrades, backup and restore drills, adding an ingest node,
certificate rotation and redacted support bundles. Ask "is there a new
version?" or "upgrade nano": it first reads every server or Kubernetes
workload without changing anything, tells you the version you run, the
latest release and what changes, lists anything that blocks the upgrade
(health, free disk, license,
.envdrift), and then walks the backup, dry run and upgrade for your install, one step at a time.
Several VMs with no single point of failure
Ask for example: "Deploy nano to these 8 VMs, about 12 GB/day, one-year
retention", or "…to VMs in AWS, about 1 TB/day". Give your agent the list
of VMs (name, private address, vCPUs, memory, data disk size and, if you know
it, which ones share a zone, rack or hypervisor) or the cloud and region. The
skill's planner (scripts/plan.py) runs on your machine, offline, and
proposes:
- which roles go on which VM: at least two app servers behind the load balancer, three PostgreSQL servers that also carry the ClickHouse Keeper quorum, ClickHouse shards with two replicas each on different failure domains, and enough ingest capacity to carry the peak with one server down. With fewer VMs it stacks roles only as far as needed (four is the minimum); with too few it says so;
- for new cloud VMs, the instance and disk types, and a monthly cost range labeled as a dated estimate, not a quote;
- the load balancer: a managed cloud load balancer, two HAProxy servers with a floating address, two HAProxy servers behind health-checked DNS, or one HAProxy server, which the plan states plainly is a single point of failure at the edge. See Load balancer options;
- the inventory, the install order across the servers, and the settings your volume needs.
It checks that losing any one VM keeps every quorum and a copy of all data.
It sizes servers from Server sizing.
If your VMs are smaller, it refuses and names what is short (for example RAM
or data disk). For an evaluation or test cluster, plan.py --lab plans
anyway and labels the plan NOT FOR PRODUCTION.
Your agent shows you the plan and changes nothing until you approve it, then
asks again before each step: license and download (checksum verified), install
in order, load balancer, a test event searched end to end, and a failover check
that stops one VM at a time. For cloud VMs it uses your own logged-in aws,
az or gcloud session and never asks for cloud keys. Above about 5,300
events per second, the plan marks its figures as extrapolated, because nano
has not been load-tested above that rate.
Several app servers and PostgreSQL failover need nano 2.0.7 or newer. On an earlier release, the plan installs one app server and one PostgreSQL server and tells you which VMs wait for the upgrade.
The skill follows the same procedures as Install with Docker Compose, High availability and Install on Kubernetes (Helm). If they ever differ, these pages win; please tell us.
Install the skill
Claude Code (personal skills directory):
mkdir -p ~/.claude/skills && curl -fsSL https://github.com/nano-rs/nano/archive/refs/heads/main.tar.gz \
| tar -xz -C ~/.claude/skills --strip-components=2 nano-main/skills/nano-deployAny agent with Agent Skills support (Claude Code, Codex, Cursor and
others), using the open skills installer:
npx skills add nano-rs/nano --skill nano-deployAgents without skill support: download the folder the same way to any
path, and tell the agent: "Read nano-deploy/SKILL.md and follow it to
deploy nano."
Use the current skill. The features these pages describe (plan.py --lab,
--lb haproxy-dns, --firewall-script and --preflight-args,
preflight.sh --exposure-probe, and fetch-bundle.sh) need the nano-deploy
skill from v2.0.8 or later. Run the install command again to update an
older copy. From v2.0.8 the skill's checks also fail on a silent outage:
the smoke test fails when a test event takes longer than 60 seconds to become
searchable (it reports the write latency), and cluster-health.py reads each
server's ClickHouse proxy and PostgreSQL and Valkey routers and fails when a
backend is down, the server's own ClickHouse first.
Then ask your agent, for example: "Deploy nano Self-run on these three hosts as 3-node HA, about 150 EPS, one-year retention."
What to have ready
| Item | Where it comes from |
|---|---|
Self-run compose bundle (nano-compose-enterprise-<version>.tar.gz), its .sha256 and .sha256.sig | The agent downloads them with the license values, then checks the checksum and signature. Or an owner or admin downloads them from app.nano.rs → Deployments → your Self-run deployment, or gives the agent the 15-minute links. See Get the bundle |
| Registry pull credential (saved to a file) | Same place |
Enrollment values LICENSE_URL, LICENSE_TOKEN, NANO_DEPLOYMENT_ID (saved to a 0600 file) | Shown once when you register the deployment |
Hosts with a non-root SSH user that has sudo | You. The agent uses your SSH agent or key file |
| App and ingest hostnames, TLS certificate or load balancer | You |
Safety rules the skill enforces
- Secrets stay in files. The agent never prints or commits the license
token, registry credential, admin password,
.env, ingest tokens or keys, and never asks you to paste one into the chat. It moves them as0600files and reads them on the host. - Read before write. Preflight is read-only. A failed check stops the deployment until you approve a fix.
- You approve every change. The agent shows the commands and hosts for each mutating step and waits. Destructive commands (deleting volumes, restores, uninstalls) need their own explicit confirmation.
- No weakening security to pass a check. No running the installer with
sudo, no skipping image digest verification, no plaintext private network outside a disposable lab, no skipped backups or bypassed upgrade gates.
Review what your agent proposes, as you would a colleague's change. You stay responsible for your hosts.
What's next
- Agent skills: every official nano skill.
- Hunt with your AI agent: hunt on your event data with the
nano-agentlaneskill.
Set up nano with your coding agent
Use Claude Code, Codex, Cursor or another coding agent to deploy nano with the nano-deploy skill, onboard sources with nano-connect and work through MCP.
Air-Gapped Deployment
Run nano inside a disconnected network with zero egress, a signed image tarball, offline content and AI, and an offline license.