Self-run
Start here if you bought nano Self-run: what it includes, your license values, installs per license, the minimum version, install methods and getting help.
nano Self-run is the paid plan for running nano on your own servers. You operate it. nano licenses it, ships its updates and gives business-hours support for the nano software.
There are two ways to run nano:
| Plan | Price | Who runs it |
|---|---|---|
| Open | Free | You, on your own servers (self-hosted) |
| Self-run | Paid | You, on your own servers (self-hosted) |
Open and Self-run use the same installer. Self-run adds your license values, which unlock the features that aren't in the open-source edition. See Deployment models.
What the plan includes
- Everything in Open: ingest, parsing, search, detections, alerting and dashboards.
- Every Self-run feature, with every license: cases, notebooks, pivt AI, risk analytics, SSO (OIDC), playbooks and custom enrichments. pivt uses the AI provider or gateway you configure. nano has no default provider.
- High availability. Run nano on three or more servers so event storage, search and ingest survive the loss of a server. See High availability. Or run it on your own Kubernetes cluster.
- The Self-run bundle and registry. Signed installer bundles and images, verified by digest at install and upgrade.
- Updates. Signed detection content and threat-intel updates every hour, and an email when a new nano version is out. See Release notes.
- Support. See Support.
Get your license values
-
Sign in to app.nano.rs as an owner or admin of your organization.
-
Open Deployments → New deployment → nano Self-run, choose your plan and pay.
-
Open the deployment's page. Under 2 · License, copy the three license values:
Value Example LICENSE_URLhttps://api.nano.rs/api/license/statusLICENSE_TOKENThe license token. It is shown only once, in that browser tab NANO_DEPLOYMENT_IDdeploy_…Save the token in your secret manager straight away.
The license values are all an install needs from app.nano.rs. With them, you or your agent can:
- download the Self-run installer bundle, without signing in to app.nano.rs;
- get a registry credential to pull the images;
- license the install. nano checks in with
api.nano.rsonce a day.
An owner or admin can also download the bundle and get a registry credential from the deployment's page. The install guides show both ways.
If the token is lost or exposed, an owner or admin can select Regenerate license token under 2 · License. The old token stops working at once. See The license shows as invalid.
Offline license (no access to api.nano.rs)
- Install with
NANO_LICENSE_MODE=offlineinstead of the license values. Then openhttps://nano.example.com/settings/licenseand copy the installation ID and organization ID. - On your deployment's page in app.nano.rs, open 2 · License → Use an offline license file instead, enter them and download the offline license.
- Import the file on the same settings page.
Download and import the next revision after each renewal. For networks with no outbound access at all, see Air-gapped deployment.
How many installs a license covers
One Self-run license covers 2 installs: production, plus one more for dev, DR or backup. A high-availability cluster counts as one install, however many servers it has.
Each install sends a random install ID with its daily license check-in, so nano can tell them apart. The daily usage of both installs is added up and compared with your plan.
A third install is never blocked. We let you know and help you sort it out. An install you retire drops off the count after 7 days without a check-in. Rebuilding an install (new servers, or a new database) gives it a new install ID, so for those 7 days the old ID still counts as one of your two installs. If you rebuilt or retired an install and want it off the count sooner, contact support and we remove it. A removed install that checks in again counts again.
The install ID travels in the X-Nano-Install-Id header. If an outbound proxy strips it, nano still runs and stays licensed, and we contact you to fix the proxy.
Minimum version: v2.0.10
Self-run needs v2.0.10 or later. Earlier v2 releases send no install ID and can't be licensed for Self-run: at their next check-in, they get a locked license that asks you to upgrade. The check-in runs once a day and at startup, so a v2.0.9 install can look fine for up to a day before the lock shows.
- New install: install the release shown on your deployment's page. It is always v2.0.10 or later.
- Existing install on v2.0.9 or earlier: run the installer again from the v2.0.10 bundle. See Upgrade a self-hosted deployment and v2.0.10.
Choose how to install
The install steps live in the install guides. They are the same for Open and Self-run; with Self-run, you add your license values.
| Layout | Use it when | Guide |
|---|---|---|
| One server (Docker Compose) | One server is enough. Most installs up to 100 GB/day | Install with Docker Compose |
| Three servers (HA, Docker Compose) | Event storage and ingest must survive the loss of a server | High availability |
| More servers (Docker Compose) | More ingest, ClickHouse or Keeper servers as you grow | Scaling past three nodes and Custom multi-node layouts |
| Kubernetes (Helm) | You already run Kubernetes, or ingest more than about 1 TB/day | Install on Kubernetes (Helm) |
| Air-gapped | The servers can't reach the internet | Air-gapped deployment |
Choose a layout for availability, not capacity. One server handles up to about 100 GB/day. To size it, see Size the host.
Network access
nano opens every outbound connection itself, over HTTPS on port 443. It never needs an inbound connection from the internet.
| Destination | When | Purpose |
|---|---|---|
api.nano.rs | Always | License check-in (daily), signed content and threat-intel updates (hourly) |
*.r2.cloudflarestorage.com | Always | Downloads of those signed updates |
us-central1-docker.pkg.dev, ghcr.io, pkg-containers.githubusercontent.com | Install and upgrade | nano images |
registry-1.docker.io, auth.docker.io, production.cloudflare.docker.com | Install and upgrade | ClickHouse, PostgreSQL, Valkey and nginx images |
quay.io, cdn01.quay.io, cdn02.quay.io, cdn03.quay.io | Install and upgrade, multi-server installs | etcd image |
storage.googleapis.com | Download | Bundle download links |
From v2.0.5, the daily license check-in also carries one number per completed UTC day: the total GB ingested, tied to the deployment ID, so nano can compare usage with your plan (Self-run Addendum Section 6.4). From v2.0.10 it also carries the install's random install ID, so the 2 installs a license covers are counted and their usage added up. Nothing else about your data is sent. With an offline license nothing is reported automatically; nano keeps the record locally and you provide it on renewal.
Open these inbound ports to your users and log sources only:
| Port | Purpose |
|---|---|
| 443 (and 80, which redirects) | UI, API, HTTP ingest at /ingest and OTLP/HTTP at /otlp/v1/* |
| 8080 | HTTP ingest straight to Vector (optional) |
| 8088 | HEC ingest |
AI providers, pull feeds, SSO, notifications and object storage connect only to the endpoints you configure. For an install with no outbound access at all, see Air-gapped deployment.
Corporate proxy
If the server reaches the internet only through an HTTP(S) proxy, answer yes when the installer asks. It then asks for:
- The proxy URL, as
http://host:port. - Whether the proxy needs a username and password. If it does, enter them.
DOMAIN\useris fine, and special characters are safe. - Any extra hosts that should bypass the proxy.
The installer saves the proxy in .env and never prints the password. nano supports proxies with no authentication or with Basic authentication. For NTLM or Kerberos, run a local forwarder such as cntlm and point nano at it.
Proxy for Docker image pulls
Create a systemd drop-in for Docker, then restart it:
# /etc/systemd/system/docker.service.d/http-proxy.conf
[Service]
Environment="HTTPS_PROXY=http://proxy.example.com:3128"
Environment="NO_PROXY=localhost,127.0.0.1"sudo systemctl daemon-reload && sudo systemctl restart dockerFor an authenticated proxy, use http://user:password@host:port with the username and password percent-encoded, and double every % (systemd reads % as a specifier). For example, CORP\svc-nano with password p@ss!word becomes http://CORP%%5Csvc-nano:p%%40ss%%21word@proxy.example.com:3128. Keep the file readable only by root (chmod 600).
Proxy details and unattended installs
- For an install with no terminal, set
NANO_HTTPS_PROXY=http://proxy.example.com:3128, plusNANO_PROXY_USERNAMEandNANO_PROXY_PASSWORDfor an authenticated proxy, and optionallyNANO_NO_PROXY. The installer encodes the credentials. SetNANO_ALLOW_PRIVATE_AI_ENDPOINTS=trueorfalseto answer the AI question. - If your shell already exports
HTTPS_PROXY, the installer offers its host and port as the default. - Reruns and upgrades never ask again. To change the proxy, edit
HTTPS_PROXY,HTTP_PROXYandNO_PROXYin.env, percent-encoding any credentials, and rundocker compose up -d. - Internal service names, loopback and the private ranges
10.0.0.0/8,172.16.0.0/12and192.168.0.0/16always bypass the proxy. The proxy must allowCONNECTto the hosts in Network access. - These connections use the proxy: license check-in, content and threat-intel updates, OIDC sign-in and directory sync, and S3 storage tiering.
- These connections never use the proxy, because nano pins each one to the address it validated: lookup URLs (
inputlookup url=), AI provider URLs, notifications and webhooks, and synthetic checks. Allow them through your firewall directly. SOAR actions and pull connectors have their own settings,SOAR_EGRESS_PROXY_URLandCONNECTOR_EGRESS_PROXY_URL(withCONNECTOR_EGRESS_PROXY_MODE=hostnameif your proxy needs host names).
Optional outbound connections
| Feature | Destination |
|---|---|
| pivt AI | Your AI provider or gateway. nano has no default provider |
| pivt docs grounding | docs-search.nano.rs, only with a docs-search token |
| Pull feeds (Okta, Entra ID, Google Workspace, Slack and others) | Each vendor's API |
| Threat-intel lookups from the marketplace | The provider you install |
| SSO | Your identity provider |
| Notifications and webhooks | Slack, Microsoft Teams, PagerDuty or your webhook URL |
| Detection as code | api.github.com |
| Storage tiering and backups to object storage | Your S3-compatible endpoint |
To stop the hourly content and threat-intel updates, set CONTENT_CHANNELS_AUTO_UPDATE=false and PLATFORM_FEEDS_AUTO_UPDATE=false in .env. To use your own mirror, set CONTENT_CHANNELS_URL and PLATFORM_FEEDS_URL. Then run docker compose up -d. Without updates, nano keeps running on the content it has.
Install with your AI agent
Claude Code, Codex and other coding agents can install nano Self-run for you with the nano-deploy agent skill. Give the agent your license values. It sizes the servers, runs a read-only preflight, installs, verifies, and handles upgrades and backups, asking before every change. It works for one server, high availability and Kubernetes. See Deploy with your AI agent.
Support
Self-run includes business-hours support by support request and email. Support is async: no phone, on-call or 24×7 coverage. Open a request with Report an issue on app.nano.rs or email support@nano.rs. Include your deployment ID and the time, with timezone. See What to include.
Support covers using the documented installer, Helm chart and upgrade steps, licensing, configuring nano, and defects in nano. It doesn't cover your own environment: hardware, OS, Docker, Kubernetes, storage, network, firewall, proxy, DNS, TLS, your identity provider, backups, cloud accounts or your AI provider. That holds even when your environment blocks an install or upgrade. If the cause is there, we tell you and point you to the docs.
For a Supported Configuration, the first response from a person comes within 1 business day for Sev 1, 3 for Sev 2 and 5 for Sev 3. See Support, the SLA and the Self-run Addendum.
Support can also take a retired install off your license count.
Troubleshoot
Install problems are covered in each guide: Docker Compose, High availability and Kubernetes.
The API won't start and names missing license settings
Set all three of LICENSE_URL, LICENSE_TOKEN and NANO_DEPLOYMENT_ID in .env, or none of them. Then run ./install.sh again.
The license shows as invalid
Check that NANO_DEPLOYMENT_ID matches app.nano.rs exactly and that the server reaches https://api.nano.rs.
If the token was lost or exposed, an owner or admin can select Regenerate license token under 2 · License on the deployment's page in app.nano.rs. The old token stops working at once and can't be recovered, and the new one is shown only once. On Docker Compose, replace LICENSE_TOKEN in ~/nano/.env, then run ./install.sh again (or docker compose up -d). On Kubernetes, see The license shows as invalid. Until you do, the install's license check-in fails, and it locks 14 days after its last successful check-in. You can also use an offline license.
The license is locked with "Upgrade required"
The install runs a v2 release before v2.0.10. Upgrade it to v2.0.10 or later. See Minimum version.
While it's locked, nano keeps only its core running:
- Keeps running: events pushed to nano (HTTP, HEC and OTLP ingest), search over the data already stored, and scheduled detection rules. Local admins (password sign-in) can still sign in and manage the license.
- Stops: SSO sign-in (OIDC) and identity-provider sync, pull collectors, cases and notebooks, SOAR playbook runs, AI features, risk and prevalence views, custom and agent enrichments, integrations, threat-intel and IOC lists, and air-gapped imports. Their API routes answer
403 LICENSE_REQUIRED.
The license page shows the lock and asks you to upgrade. The upgrade removes the lock: the upgraded install checks in when it starts.
Monitor your Self-run install
Watch nano's own health with Prometheus and Grafana on a single node, a role-split cluster or Kubernetes, and send nano's health alerts into nano.
High availability
Run nano Self-run on three Linux servers so event storage, search and ingest survive the loss of one server.