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.
Use your own coding agent to go from an empty host to a working nano Self-run install with your first log sources. You load nano's agent tools into the agent, tell it your volume and where nano should run, and approve each step it proposes.
The agent uses four tools, one for each stage:
| Stage | Tool | What it is |
|---|---|---|
| Deploy | nano-deploy | An Agent Skill: instructions and scripts your agent follows to size, preflight, install, verify and upgrade nano Self-run |
| Connect logs | nano-connect | A Bash script that generates collectors, issues one ingest token per source and proves events arrive |
| Operate | nano-investigator | An MCP server to search, triage, investigate, hunt and build parsers |
| Operate | nanodac | An MCP server and CLI for detections as code |
Inside the product, pivt helps with queries, detections, dashboards, parsers and case investigation once you configure your own model provider.
Before you start
You need:
- A coding agent on your workstation. The skill works with Claude Code, Codex, Cursor, Antigravity and other agents that support Agent Skills. Any agent that can read a file can follow it.
ssh,scp,python3andbashon the workstation.- A Self-run deployment at app.nano.rs. Save its enrollment values (
LICENSE_URL,LICENSE_TOKEN,NANO_DEPLOYMENT_ID) to a file with mode0600. The token is shown once. - Linux hosts with a non-root SSH user that has
sudo, or a Kubernetes cluster withkubectlandhelm. For new VMs on AWS, Azure or GCP, your own logged-inaws,azorgcloudCLI. - App and ingest hostnames, and a TLS certificate or a load balancer.
Deploy nano
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-deployCodex, Cursor, Antigravity and other agents with Agent Skills support, using the open skills installer:
npx skills add nano-rs/nano --skill nano-deployFor an agent without skill support, download the folder to any path and tell the agent: "Read nano-deploy/SKILL.md and follow it to deploy nano." Run the install command again to update the skill.
Ask your agent to deploy
Tell it the layout, your volume and retention, the hosts, and where the enrollment file is. For example:
- "Deploy nano Self-run on nano-1.internal as a single node. About 20 GB/day, 365 days retention. My enrollment values are in ~/nano/enrollment.env."
- "Deploy nano Self-run on these three hosts as 3-node HA, about 150 EPS, one-year retention."
- "Deploy nano to these 8 VMs, about 12 GB/day, one-year retention."
- "Plan nano on new VMs in AWS for about 1 TB/day. Show me the plan before you create anything."
The agent asks for anything you left out, then sizes the deployment from your volume and retention. For a cluster of several VMs, its planner lays out the roles on your VMs, or picks new VMs on AWS, Azure or GCP, and refuses when the VMs are too small. See Deploy with your AI agent for the layouts and what the planner checks. Nothing is created or installed until you confirm the plan.
Review the preflight
The agent runs a read-only preflight over SSH on every host: OS, CPU and AVX2, memory, disk, Docker and Compose, time sync, ports and connectivity between hosts. It prints one PASS, WARN or FAIL row per check. Any FAIL stops the deployment until you approve a fix.
On Kubernetes, the preflight runs through kubectl instead: cluster and Helm versions, a storage class, the Gateway API, node pools and AVX2, and, for an external PostgreSQL, version, schema permissions and extensions. The agent then installs nano's Helm chart (digest-pinned images, pulled with your license's registry credential) rather than the Compose bundle. See Kubernetes (Helm).
Approve each install step
The agent downloads the release with your enrollment values, checks the signature and checksum, and installs in the documented order. Before each step that changes something, it shows the commands and the hosts and waits for your confirmation. Destructive commands need their own explicit confirmation.
Check the verification
The agent reports a table of checks: the health endpoints, admin login, license state, and a unique test event ingested and found by search. On HA it also checks Keeper quorum and ClickHouse replica health. A failed check is reported as failed, with the evidence.
Later, ask "Is there a new version of nano?" or "Upgrade nano". The agent reads every host without changing anything, reports your version, the latest release and anything that blocks the upgrade, then walks the backup, dry run and upgrade one step at a time.
Connect log sources
Every install starts with zero log sources. Choose what to onboard, and let your agent run nano-connect for those sources. It is a plain Bash script, not an AI tool; its --non-interactive mode lets an agent drive it.
Create an API key for nano-connect
Create a key under Settings → Access Control → API Keys with only the permissions nano-connect uses: log_sources:view to discover sources, settings:system to issue ingest tokens, parser_repositories:import, log_sources:create, source_configs:edit and log_sources:deploy for --deploy-parsers, and search:execute to prove delivery. Put it in your secret manager and export it as NANO_API_KEY, with NANO_URL set to your nano base URL.
Ask your agent to onboard a source
For example: "Download nano-connect, review it, and set up a syslog collector for our Cisco ASA and Palo Alto firewalls on this host. Then prove events arrive." The agent runs commands like these:
curl -fsSL https://github.com/nano-rs/connect/releases/latest/download/connect.sh -o connect.sh
bash connect.sh --version
bash connect.sh list-sources
bash connect.sh add-source --sources cisco_asa,palo_alto:tcp \
--deploy-parsers --out-dir ./fw-collector --non-interactiveadd-source imports and publishes the parser for each source you name that isn't a log source yet, issues one ingest token per source, and writes vector.toml, docker-compose.yml and a private secrets/ directory. It starts nothing unless you pass --run. Linux and Windows endpoints use add-agent; see Generate a collector.
Prove delivery
bash connect.sh connect --source cisco_asa --non-interactive
bash connect.sh verify --source cisco_asa --non-interactiveconnect sends a marked test event and waits until search finds it under the source. After you point the devices at the collector, verify checks for fresh events from the last 15 minutes.
Work in nano with MCP
Add the nano-investigator and nanodac MCP servers to the same agent. Both run locally over stdio and read NANOSIEM_API_URL (your nano base URL, not the ingest hostname) and NANOSIEM_API_KEY. For Claude Code, add them to a project .mcp.json:
{
"mcpServers": {
"nano-investigator": {
"command": "npx",
"args": ["-y", "@nano-rs/investigator-mcp-server"],
"env": {
"NANOSIEM_API_URL": "https://nano.example.com",
"NANOSIEM_API_KEY": "${NANOSIEM_API_KEY}"
}
},
"nanodac": {
"command": "npx",
"args": ["-y", "@nano-rs/dac-mcp-server"],
"env": {
"NANOSIEM_API_URL": "https://nano.example.com",
"NANOSIEM_API_KEY": "${NANOSIEM_API_KEY}"
}
}
}
}Other MCP clients, such as Cursor or Antigravity, take the same command, arguments and environment in their own MCP configuration. Restart the agent; in Claude Code, run /mcp to confirm both servers are connected.
Give each server an API key scoped to its job. A key carries an explicit permission list and can't exceed its owner's permissions. Read-only investigation needs search:execute, search:view, alerts:view, cases:view and risk:view, among others; see API key permissions. nanodac needs detections:view, detections:create and search:execute to read and test, and detections:edit to sync; see nanodac setup.
Then ask, for example:
> how many alerts fired today?
> investigate alert 456
> hunt for lateral movement in the last 7 days
> build a parser for these logs
> draft a detection for repeated failed logins followed by a success, and test itTurn on pivt
pivt is nano's assistant inside the product and is included with Self-run. It stays off until you configure a provider under Settings → AI & pivt: any OpenAI-compatible endpoint, including a model you run yourself, or the Anthropic API. See AI & pivt.
Troubleshoot
Need help with these checks? Contact support with your deployment ID and the time with timezone.
The agent doesn't use the skill
Check that the skill folder is where your agent loads skills from (for Claude Code, ~/.claude/skills/nano-deploy/SKILL.md), and restart the agent. You can also tell it: "Read nano-deploy/SKILL.md and follow it."
Preflight reports FAIL
The agent stops on any FAIL row. Approve or apply the fix it proposes, for example installing Docker Engine from Docker's repository, then ask it to run the preflight again.
nano-connect returns 403
The API key is missing a permission. Discovery needs log_sources:view; issuing tokens needs settings:system. See nano-connect troubleshooting.
An MCP server doesn't connect
Check NANOSIEM_API_URL and NANOSIEM_API_KEY, restart your agent, and run /mcp in Claude Code. See Investigator setup.
What's next
- Deploy with your AI agent: layouts, the planner and the skill's safety rules
- nano-connect CLI: collectors, transports and tokens
- Agents & MCP: nano-investigator, nanodac and pivt
- Set up your first feed
Custom multi-node layouts
Split nano Self-run across Linux servers in a layout other than the standard three-node HA design, with a reviewed inventory.
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.