nano SIEM
Agents & MCP

Agent Lane

Supported in:Self-hosted

A read-only, audited fast lane for AI agents onto nano's event data: native ClickHouse SQL over a dedicated HTTPS listener, with named, expiring tokens. nano Self-run only.

Agent Lane gives AI agents and scripts a direct, read-only path to nano's event data. An agent connects to a dedicated HTTPS listener on ClickHouse (port 8444 by default) with its own token and runs native ClickHouse SQL. It does not go through the nano API or the search service, so hunts are fast, and it runs at low priority so it doesn't slow ingest, detections or your analysts.

Agent Lane is part of nano Self-run (v2.0.23 or later). The open-core edition doesn't include it. It is off by default, including after an upgrade.

To let a coding agent hunt through Agent Lane, install the nano-agentlane skill: see Hunt with your AI agent.

How it works

Turning Agent Lane on takes two switches:

  1. The listener, a deployment setting. You turn it on in .env (single host), the inventory (role split) or Helm values, with an IP allow-list and a TLS certificate. Until then nothing listens on the port.
  2. The Agent Lane switch in Settings → Agent Lane. With it on, an administrator creates tokens. Each token gets its own ClickHouse login, created on every ClickHouse node.

An agent signs in with the token over HTTPS (ClickHouse's HTTP interface over TLS) and sends SQL. Every query it runs is written to nano's audit log under that token.

Security model

  • Read-only. A token can't write, change the schema, reach other systems through ClickHouse, or read other users' queries. It can't raise its own limits.
  • What a token reads. Every token reads the same data: events, detection signals, identity history and prevalence. nano's own audit events are hidden. Tokens are not scoped by Source visibility: a token reads events from every log source, including restricted ones. This is by design: Agent Lane is for trusted automation that hunts across all data, so treat creating a token as granting read access to all event data.
  • Token-scoped. Each token is named, expires after at most 90 days and can be revoked at any time. Its secret is shown once; nano keeps only a salted hash. A token can carry its own IP allow-list, and it inherits the install-wide list when it has none.
  • Network allow-list. The listener admits only the install-wide allow-list. On a single host an nftables table enforces it, with per-source limits on new and open connections. On Kubernetes the Service's loadBalancerSourceRanges and a NetworkPolicy enforce it. An allow-list that admits everyone (any /0 entry) is refused. ClickHouse's own HTTP (8123) and native (9000) ports stay internal.
  • Internal users stay internal. nano's other ClickHouse users accept connections only from internal networks, so they can't sign in on the Agent Lane port. nano checks this continuously. If any other user could sign in from outside, Settings refuses to switch Agent Lane on or create a token, and SIEM Health raises a critical finding. See Troubleshoot.
  • Limits. Fixed per-query caps, per-install read and memory budgets, per-token quotas and a cap on active tokens. See Limits.
  • Audit. Every query, refusal and failed login is recorded per token. See Audit trail.
  • TLS. The listener uses its own certificate and TLS 1.2 or later with modern cipher suites only. Agents verify it; never turn verification off.
  • Administrator authority. The Settings page needs the agentlane:manage permission. Switching Agent Lane on and creating a token also need administrator authority, because both grant read access to all event data. Switching off and revoking need only agentlane:manage, and stay available at the license hard stop so you can always remove access.

The allow-lists depend on ClickHouse seeing each agent's real source address. Don't put a proxy or NAT that rewrites source addresses in front of the listener.

Enable the listener

You need a TLS certificate and key dedicated to Agent Lane, for a host name agents connect to, and the networks your agents connect from. The allow-list must not overlap nano's internal networks (loopback and the Docker address pools on a single host, the host addresses on a role split, clickhouse.allowedNetworks on Kubernetes). The installers refuse an overlapping list.

Single host (Compose)

Requirements: systemd, nftables and python3 on the host.

Docker address pools. Docker's default pools are 172.16.0.0/12 and 192.168.0.0/16, and nano's ClickHouse users accept those ranges. If your agents are on a 192.168.x or 172.16-31.x network, move Docker's pools first. Set a range nothing else uses in /etc/docker/daemon.json, merged with any existing settings:

{
  "default-address-pools": [
    { "base": "10.210.0.0/16", "size": 24 }
  ]
}

Then stop nano (docker compose ... down, without -v), run sudo systemctl restart docker (this restarts every container on the host) and re-run install.sh.

  1. Add to .env:

    NANO_AGENTLANE_LISTENER=true
    # Required. Agent source networks, comma or space separated.
    NANO_AGENTLANE_ALLOW_CIDRS=203.0.113.0/24,198.51.100.7
    # Required. Absolute paths; they may be root-only.
    NANO_AGENTLANE_TLS_CERT=/etc/letsencrypt/live/agents.example.com/fullchain.pem
    NANO_AGENTLANE_TLS_KEY=/etc/letsencrypt/live/agents.example.com/privkey.pem
    # Optional (defaults shown).
    NANO_AGENTLANE_PORT=8444
    NANO_AGENTLANE_PUBLIC_URL=https://<BASE_URL host>:8444   # shown in Settings
    NANO_AGENTLANE_RATE_PER_MINUTE=120           # new connections per source
    NANO_AGENTLANE_MAX_CONN_PER_SOURCE=32        # open connections per source
  2. Run ./install.sh as usual, without root. It renders the listener, publishes nothing yet, and prints the one command that needs root:

    sudo bash /opt/nano/deploy/compose/agentlane/nano-agentlane-host apply /opt/nano

    This loads the firewall rules for the port and makes Docker wait for them at boot, so the port is never published unfiltered. It also installs a timer that restores the rules if they change and picks up a renewed certificate, and copies the certificate and key to a root-only directory.

  3. Run ./install.sh again as the same user. It checks the firewall and boot units, then publishes the port and adds the Agent Lane overlay to NANO_COMPOSE_OVERLAYS, so scripts/nano upgrade keeps it.

If the allow-list, port or certificate paths change later, install.sh withdraws the listener until you re-run nano-agentlane-host apply. A certificate renewed at the same paths needs nothing.

The listener binds IPv4 only, and the firewall has no interface exemptions: a container on the nano host is never an agent source. Run agents on other machines.

Role split (multi-node Compose)

The listener runs on ClickHouse hosts you choose, never on ingest-only or app-only hosts. Add to the inventory:

agentlane:
  enabled: true
  allow_cidrs: [203.0.113.0/24]
  tls:
    cert: /etc/nano/agentlane/fullchain.pem   # on every listener host
    key: /etc/nano/agentlane/privkey.pem
  # Optional: port (8444), public_url (default https://<first listener host>:<port>),
  # rate_per_minute (120), max_connections_per_source (32).
hosts:
  - name: clickhouse-1
    roles: [clickhouse]
    agentlane: true

On each listener host run install.sh --role clickhouse ... to render, then sudo bash ~/nano/deploy/compose/agentlane/nano-agentlane-host apply ~/nano, then install.sh again. Turning Agent Lane on or off needs no topology migration.

If the host uses UFW with default deny incoming, also allow the port:

sudo ufw allow from 203.0.113.0/24 to any port 8444 proto tcp

Kubernetes (Helm)

Agent Lane on Helm requires clickhouse.allowedNetworks. The chart refuses to render the listener while it is empty, because then every nano ClickHouse user accepts any address.

clickhouse:
  allowedNetworks: ["127.0.0.1", "::1", "10.0.0.0/8", "fc00::/7"]  # your pod and node CIDRs
agentlane:
  enabled: true
  port: 8444
  allowCidrs: [203.0.113.0/24, 198.51.100.7/32]   # required; any /0 is refused
  publicUrl: https://agents.example.com:8444       # shown in Settings
  tls:
    secretName: agentlane-tls   # kubernetes.io/tls; empty reuses the app certificate
  service:
    type: LoadBalancer          # or NodePort
  networkPolicy:
    enabled: true

The chart renders a TLS listener on every ClickHouse server, a separate <release>-agentlane Service with externalTrafficPolicy: Local and loadBalancerSourceRanges set to allowCidrs, and a NetworkPolicy on the ClickHouse pods. It gives the API and jobs Deployments the same Agent Lane settings. helm test checks the ClickHouse users on every replica.

With an AWS NLB using IP targets, enable preserve_client_ip.enabled=true or use instance targets, or ClickHouse sees the NLB's address. With NodePort, your firewall or security group must carry the allow-list. See Install on Kubernetes (Helm) for the chart.

Check the listener

From an allow-listed machine:

curl -sS https://agents.example.com:8444/ping          # Ok.

From anywhere else the connection should time out, and ports 8123 and 9000 should be closed from outside. On a Compose host, sudo nft list table inet nano_agentlane shows the allow-list and drop counters.

Manage tokens

Open Settings → Agent Lane. The page shows the listener and switch state, the install-wide allow-list, the public URL agents connect to, the last reconcile and the token cap.

Switch Agent Lane on

Click Turn Agent Lane on. It needs administrator authority and an install-wide allow-list. The change is audited.

Create a token

Click New token and set:

  • Name, for example hunt-agent-prod.
  • Expires in: 7, 30 or 90 days, or any value up to the maximum of 90.
  • IP allow-list (optional): addresses or CIDRs the token may connect from, no wider than /8 for IPv4 or /32 for IPv6. Empty inherits the install-wide list.
  • Quota: Low, Standard (default) or High. See Per-token quotas.

The token (nal_<id>_<secret>) is shown once, together with the ClickHouse username, password and connect URL. Save it straight into a secret store or a 0600 file for the agent. nano can't show it again.

Rotate a token

There is no in-place rotation. Create a new token, move the agent to it, then revoke the old one. Rotate whenever a token may have been exposed, for example if it was pasted into a chat.

Revoke a token

Click Revoke on the token and give an optional reason (audited). nano drops the token's ClickHouse user and quota and kills its running queries on every node; the next request with the token is refused. The token's history stays in the list and the audit log. Expired tokens are dropped the same way.

Download the agent kit

Agent kit → Download schema saves a JSON file with the tables and columns a token can read on this install, the nano version, the connection details and the skill install command. It never contains a token. Give it to your agent so it queries the right tables and columns.

Connect

Agents need:

  • The URL: the public URL shown in Settings, HTTPS on port 8444 unless you changed it.
  • The login: user agentlane_<id> and the secret as password, split from the token at the first two underscores. HTTP basic auth.
  • The CA certificate, only if the listener uses a private CA.

The listener speaks HTTPS only, so use an HTTP client: curl, Python clickhouse-connect or the JavaScript @clickhouse/client. The native clickhouse-client can't connect.

A quick check, with the login in a 0600 netrc file so the password never appears on a command line:

echo "SELECT currentUser(), getSetting('readonly') FORMAT TSV" |
  curl -sS --fail-with-body --netrc-file ~/.config/nano/agentlane.netrc \
    "https://agents.example.com:8444/?log_comment=my-session" --data-binary @-

It prints the token's user and 1 (read-only). The nano-agentlane skill walks an agent through the token split, the netrc file and the TLS setup.

Every query must filter on timestamp (observed_at on identity_observations). Pass values as query parameters and set log_comment to the agent's session id so its queries group together in the audit log. On a cluster, query the *_distributed tables.

Limits

Every limit is per ClickHouse node. An agent that reaches N nodes, through a load balancer or several listener hosts, gets N times each limit in total.

Fixed per-query caps

These can't be raised; an agent may only lower the first two.

CapValue
Execution time60 s
Result rows100,000
Result size64 MiB
Concurrent queries per token2 (a third is refused at once, never queued)
Statements per request1
Time filterrequired on timestamp

The time filter is enforced but doesn't bound the range: a very wide window passes the check and then stops at the read cap.

Per-install settings

Compose: set the variable in .env and re-run install.sh. Helm: set the key under migrations.. Sizes are in bytes.

Compose .envHelm migrations.Default
NANO_AGENTLANE_MAX_ROWS_TO_READagentlaneMaxRowsToRead500,000,000
NANO_AGENTLANE_MAX_BYTES_TO_READagentlaneMaxBytesToRead50 GiB
NANO_AGENTLANE_MAX_CONCURRENT_THREADSagentlaneMaxConcurrentThreads2
NANO_AGENTLANE_MAX_MEMORY_PER_TOKENagentlaneMaxMemoryPerTokenmin(4 GiB, ¼ of the node's memory limit), at least 256 MiB
NANO_AGENTLANE_WORKLOAD_MAX_MEMORYagentlaneWorkloadMaxMemory¼ of the node's memory limit, at least 512 MiB
  • The read caps bound a scan. The defaults cover several days of a 50 to 100 GB/day install.
  • The thread cap keeps agents from slowing ingest, detections and analysts. On an install where agent hunts matter more than that headroom, raise it in steps and watch detection lag and analyst search times in SIEM Health after each one.
  • Memory is capped per token and for all agent queries together. Under memory pressure ClickHouse stops agent queries first; ingest, detections and analysts are never stopped for an agent.

Active-token cap

The number of live tokens is capped at the workload memory budget divided by the per-token budget, between 1 and 10. Settings → Agent Lane shows the cap and lets you lower it. To allow more tokens, raise the workload budget, lower the per-token budget or give ClickHouse more memory. Lowering the cap below the current count revokes nothing; new tokens are refused until it fits.

Per-token quotas

Each token's quota tier bounds sustained use, per token, per node. Seconds are total query execution time.

TierPer hourPer day
Low120 queries, 30 errors, 50 GiB read, 600 s1,000 queries, 200 errors, 500 GiB read, 3,600 s
Standard (default)600 queries, 100 errors, 500 GiB read, 1,800 s5,000 queries, 1,000 errors, 5 TiB read, 14,400 s
High2,400 queries, 400 errors, 2 TiB read, 3,600 s20,000 queries, 4,000 errors, 20 TiB read, 43,200 s

A token over its quota gets ClickHouse error 201 until the interval ends.

Audit trail

nano records every Agent Lane query in the audit log under its token, within about 30 seconds:

ActionWhen
agentlane_queryA query ran. Includes the full query text, log_comment and resource use. success is false when ClickHouse raised an error.
agentlane_query_refusedA query was refused on the token's quota (201) or concurrency cap (202).
agentlane_login_failedA failed login with an Agent Lane user name. Recorded only when ClickHouse writes system.session_log.
agentlane_enabled, agentlane_disabledAn administrator switched Agent Lane on or off.
agentlane_token_created, agentlane_token_revoked, agentlane_token_expiredToken lifecycle.

The audited query text keeps every literal value the agent searched for (indicators, names, addresses) for as long as audit events are kept, readable by anyone with audit:view.

The Tokens table in Settings shows each token's queries, bytes read and refusals over the last 24 hours, and when it was last used. The page also shows how far the query audit lags behind.

SIEM Health findings

FindingMeaning
ClickHouse users are reachable on the Agent Lane port (critical)A ClickHouse user other than a token user accepts connections from outside. nano stops creating or repairing token users until it is fixed.
Agent Lane reconciler is misconfiguredThe listener is on, but the jobs service has no usable allow-list. Existing token users are kept unchanged.
Agent Lane query audit is behindThe harvester can't keep up with, or can't read, a ClickHouse node's query log.
Agent Lane tokens are hitting their quotaTokens are being refused on quota or concurrency.
Failed Agent Lane logins from unknown addressesLogins with Agent Lane user names are failing.
Agent Lane has N live tokens but allows MMore live tokens than the cap, for example after a restore onto a smaller node. New tokens are refused.
Agent Lane cannot read its memory budgetsThe cap fell back to 1 because a node's budgets couldn't be read.

Turn it off

  1. Switch Agent Lane off in Settings → Agent Lane. This drops every token's ClickHouse user on every node and kills their queries at once. Tokens are kept and work again when you switch it back on; revoke any you no longer want.
  2. Remove the listener:
    • Single host: set NANO_AGENTLANE_LISTENER=false and run install.sh, then remove the firewall table and staged certificate with sudo bash <install-dir>/deploy/compose/agentlane/nano-agentlane-host remove.
    • Role split: remove agentlane: true from the host (or set agentlane.enabled: false), run install.sh, then remove as above.
    • Helm: set agentlane.enabled: false and upgrade.

With the listener off, token users are dropped within a minute even if you skipped the Settings switch. Settings shows listener off and lists live tokens as inactive, and new tokens are refused.

Troubleshoot

Settings refuses to switch on or create a token

ErrorFix
allowlist_requiredThe install has no usable allow-list. Set it on the listener and re-run the installer.
listener_offThe listener is off on this install. Enable the listener first.
clickhouse_users_exposedSee the next section.
clickhouse_users_unverifiedA ClickHouse node couldn't be checked, for example a replica restarting. Retry once every node is up.
active_token_capThe cap is full. Revoke a token, or raise the budgets as in Active-token cap.
license_requiredThe license hard stop. Status, revoke and switch-off still work.
403 without a codeYour role lacks agentlane:manage or administrator authority.

ClickHouse users are reachable on the Agent Lane port

The error and the SIEM Health finding name each user. Restrict each to loopback and the internal networks, or drop it, for example:

ALTER USER reporting HOST IP '127.0.0.1', IP '::1', IP '172.16.0.0/12'

Create every ClickHouse user with an explicit HOST list. A user created without one accepts any address until the next reconcile pass detects it.

The agent can't connect

  • Connection times out: the agent's address isn't on the install-wide allow-list, or a firewall in between drops it. On a role split with UFW, allow the port. On Kubernetes, check the Service's source ranges and that externalTrafficPolicy is Local.
  • Code: 516 AUTHENTICATION_FAILED: the token is expired or revoked, its user and password were split wrongly (split only at the first two underscores), or the agent's address isn't on the token's own allow-list.
  • Certificate error: the agent doesn't trust a private CA, or the certificate doesn't cover the host name in the URL.
  • Tokens stop working a minute after creation: you are on v2.0.23. Upgrade and re-run install.sh.
  • Install refuses the allow-list: it overlaps nano's internal networks. On a single host, move Docker's address pools as in Single host.

Queries are refused

CodeMeaning
277No time filter on timestamp.
158, 307The read cap. Narrow the window or add a class_uid or source_type filter.
159The 60-second timeout.
396The result is over 100,000 rows or 64 MiB. Aggregate or add a LIMIT.
201The token's quota. Wait until the interval ends.
202Two queries are already running for this token.
497The table or function isn't granted to Agent Lane.
164, 452The query set a setting the lane doesn't allow, or raised a capped one.

What's next

On this page