Agent Lane
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:
- 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. - 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
loadBalancerSourceRangesand a NetworkPolicy enforce it. An allow-list that admits everyone (any/0entry) 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:managepermission. 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 onlyagentlane: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.
-
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 -
Run
./install.shas 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/nanoThis 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.
-
Run
./install.shagain as the same user. It checks the firewall and boot units, then publishes the port and adds the Agent Lane overlay toNANO_COMPOSE_OVERLAYS, soscripts/nano upgradekeeps 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: trueOn 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 tcpKubernetes (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: trueThe 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
/8for IPv4 or/32for 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
8444unless 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.
| Cap | Value |
|---|---|
| Execution time | 60 s |
| Result rows | 100,000 |
| Result size | 64 MiB |
| Concurrent queries per token | 2 (a third is refused at once, never queued) |
| Statements per request | 1 |
| Time filter | required 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 .env | Helm migrations. | Default |
|---|---|---|
NANO_AGENTLANE_MAX_ROWS_TO_READ | agentlaneMaxRowsToRead | 500,000,000 |
NANO_AGENTLANE_MAX_BYTES_TO_READ | agentlaneMaxBytesToRead | 50 GiB |
NANO_AGENTLANE_MAX_CONCURRENT_THREADS | agentlaneMaxConcurrentThreads | 2 |
NANO_AGENTLANE_MAX_MEMORY_PER_TOKEN | agentlaneMaxMemoryPerToken | min(4 GiB, ¼ of the node's memory limit), at least 256 MiB |
NANO_AGENTLANE_WORKLOAD_MAX_MEMORY | agentlaneWorkloadMaxMemory | ¼ 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.
| Tier | Per hour | Per day |
|---|---|---|
| Low | 120 queries, 30 errors, 50 GiB read, 600 s | 1,000 queries, 200 errors, 500 GiB read, 3,600 s |
| Standard (default) | 600 queries, 100 errors, 500 GiB read, 1,800 s | 5,000 queries, 1,000 errors, 5 TiB read, 14,400 s |
| High | 2,400 queries, 400 errors, 2 TiB read, 3,600 s | 20,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:
| Action | When |
|---|---|
agentlane_query | A query ran. Includes the full query text, log_comment and resource use. success is false when ClickHouse raised an error. |
agentlane_query_refused | A query was refused on the token's quota (201) or concurrency cap (202). |
agentlane_login_failed | A failed login with an Agent Lane user name. Recorded only when ClickHouse writes system.session_log. |
agentlane_enabled, agentlane_disabled | An administrator switched Agent Lane on or off. |
agentlane_token_created, agentlane_token_revoked, agentlane_token_expired | Token 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
| Finding | Meaning |
|---|---|
| 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 misconfigured | The listener is on, but the jobs service has no usable allow-list. Existing token users are kept unchanged. |
| Agent Lane query audit is behind | The harvester can't keep up with, or can't read, a ClickHouse node's query log. |
| Agent Lane tokens are hitting their quota | Tokens are being refused on quota or concurrency. |
| Failed Agent Lane logins from unknown addresses | Logins with Agent Lane user names are failing. |
| Agent Lane has N live tokens but allows M | More live tokens than the cap, for example after a restore onto a smaller node. New tokens are refused. |
| Agent Lane cannot read its memory budgets | The cap fell back to 1 because a node's budgets couldn't be read. |
Turn it off
- 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.
- Remove the listener:
- Single host: set
NANO_AGENTLANE_LISTENER=falseand runinstall.sh, then remove the firewall table and staged certificate withsudo bash <install-dir>/deploy/compose/agentlane/nano-agentlane-host remove. - Role split: remove
agentlane: truefrom the host (or setagentlane.enabled: false), runinstall.sh, thenremoveas above. - Helm: set
agentlane.enabled: falseand upgrade.
- Single host: set
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
| Error | Fix |
|---|---|
allowlist_required | The install has no usable allow-list. Set it on the listener and re-run the installer. |
listener_off | The listener is off on this install. Enable the listener first. |
clickhouse_users_exposed | See the next section. |
clickhouse_users_unverified | A ClickHouse node couldn't be checked, for example a replica restarting. Retry once every node is up. |
active_token_cap | The cap is full. Revoke a token, or raise the budgets as in Active-token cap. |
license_required | The license hard stop. Status, revoke and switch-off still work. |
| 403 without a code | Your 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
externalTrafficPolicyisLocal. 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
| Code | Meaning |
|---|---|
| 277 | No time filter on timestamp. |
| 158, 307 | The read cap. Narrow the window or add a class_uid or source_type filter. |
| 159 | The 60-second timeout. |
| 396 | The result is over 100,000 rows or 64 MiB. Aggregate or add a LIMIT. |
| 201 | The token's quota. Wait until the interval ends. |
| 202 | Two queries are already running for this token. |
| 497 | The table or function isn't granted to Agent Lane. |
| 164, 452 | The query set a setting the lane doesn't allow, or raised a capped one. |
What's next
pivt
nano's built-in AI assistant: the @ command panel, AI wizards for detections, tuning, dashboards, parsers and queries, and background case investigation.
Agent skills
The official nano agent skills, nano-deploy and nano-agentlane, for Claude Code, Codex and other coding agents. How to install them, how they're versioned and what they will and won't do.