nano SIEM
Getting Started

Deploy with your AI agent

Supported in:Self-hosted

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:

  1. 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.
  2. Sizing. It sizes the hosts from your EPS or GB/day and retention, using the sizing guide.
  3. 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.
  4. 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.
  5. 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.
  6. 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, .env drift), 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-deploy

Any agent with Agent Skills support (Claude Code, Codex, Cursor and others), using the open skills installer:

npx skills add nano-rs/nano --skill nano-deploy

Agents 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

ItemWhere it comes from
Self-run compose bundle (nano-compose-enterprise-<version>.tar.gz), its .sha256 and .sha256.sigThe 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 sudoYou. The agent uses your SSH agent or key file
App and ingest hostnames, TLS certificate or load balancerYou

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 as 0600 files 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

On this page