nano SIEM
Getting Started

Set up nano with your coding agent

Supported in:Self-hosted

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:

StageToolWhat it is
Deploynano-deployAn Agent Skill: instructions and scripts your agent follows to size, preflight, install, verify and upgrade nano Self-run
Connect logsnano-connectA Bash script that generates collectors, issues one ingest token per source and proves events arrive
Operatenano-investigatorAn MCP server to search, triage, investigate, hunt and build parsers
OperatenanodacAn 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, python3 and bash on 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 mode 0600. The token is shown once.
  • Linux hosts with a non-root SSH user that has sudo, or a Kubernetes cluster with kubectl and helm. For new VMs on AWS, Azure or GCP, your own logged-in aws, az or gcloud CLI.
  • 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-deploy

Codex, Cursor, Antigravity and other agents with Agent Skills support, using the open skills installer:

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

For 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-interactive

add-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-interactive

connect 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 it

Turn 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

On this page