Administer hunts
Set up AI for hunts, check the server runner, configure the scheduler and retention, and grant hunt permissions.
Set up hunts for your team. Assign AI models to the hunt agents, check the server runner, decide how long hunt history is kept, and grant permissions.
Set up AI for hunts
The server runner and the reviewer use the AI provider you configure in nano.
- Configure a provider in Settings → AI & pivt → Providers. See AI & pivt.
- Click Agent Models.
- In the Hunt group, assign a model to each hunt agent.
| Agent | Default model | What it does |
|---|---|---|
Hunt investigator (hunt_investigator) | workers-ai/@cf/zai-org/glm-5.3 | Investigates each run |
Hunt reviewer (hunt_reviewer) | workers-ai/@cf/zai-org/glm-5.3 | Checks each lead |
Hunt recheck (hunt_recheck) | workers-ai/@cf/zai-org/glm-5.3-flash | Checks known attackers |
The investigator and reviewer models must support tool calling. If you have more than one provider, consider giving the reviewer a model from a different family than the investigator. nano measures the reviewer's accuracy separately for each model.
Reasoning effort
The hunt agents use low reasoning effort by default. At higher effort, a reasoning model can use its whole output allowance on thinking and never run a query. If you changed an agent's effort, nano keeps your setting.
The Agent Models page doesn't show reasoning effort. To change it, call the API. You need settings:agent_models.
curl -X PUT "https://<your-nano-host>/api/settings/agent-models/hunt_reviewer" \
-H "X-API-Key: $NANO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reasoning_effort": "low"}'Check the server runner
- Click Hunts, then Runners.
- Check that the server runner shows online and lists your investigator model.
The server runner needs:
- an AI provider, and an investigator model that supports tool calling;
- a valid license;
- the jobs service's database administrator credentials, which it uses to create its own read-only user;
- a free connection slot. There are 6 by default, and fewer on small installations.
It doesn't need the Agent Lane switch, listener, or allow-list that external agents use.
Server runner settings
Set these environment variables on the jobs service (nano-jobs). Each applies to one jobs instance.
| Variable | Default | Meaning |
|---|---|---|
NANO_HUNTS_SERVER_RUNNER | on | Set to off to stop the server runner |
NANO_HUNTS_SERVER_CONCURRENCY | 1 | Runs at the same time on this instance, 1 or 2 |
NANO_HUNTS_RUNNER_LABEL | nano-jobs and the node name | The runner's name. Give each instance on one node its own name. |
NANO_HUNTS_REVIEWER_DESKTOP_GRACE_SECS | 600 | Seconds to wait after a Desktop run before the server reviews its leads |
Scheduler settings
| Variable | Meaning |
|---|---|
HUNT_SCHEDULER_ENABLED | Set to false to stop all scheduled runs. Hunts then run only with Run now. |
HUNT_SCHEDULER_POLL_INTERVAL_SECS | How often, in seconds, nano checks for hunts that are due |
HUNT_SCHEDULER_BATCH_SIZE | Most hunts queued on each check |
Retention
nano cleans up hunt history once an hour. Set these environment variables on the jobs service to change how long it keeps each kind of data.
| Data | Default | Variable |
|---|---|---|
| Suppressions that stop matching | Expire after 60 days | HUNT_RETENTION_SUPPRESSION_IDLE_DAYS |
| Expired or revoked suppressions | Deleted 30 days later | HUNT_RETENTION_SUPPRESSION_GRACE_DAYS |
| Expired baselines and notes | Deleted 30 days later | HUNT_RETENTION_KNOWLEDGE_GRACE_DAYS |
| Revoked baselines and notes | Kept, so they can't be learned again (0 means never delete) | HUNT_RETENTION_REVOKED_KNOWLEDGE_DAYS |
| Dismissed findings | Deleted after 180 days | HUNT_RETENTION_DISMISSED_LEAD_DAYS |
| Finished runs | Deleted after 90 days | HUNT_RETENTION_SWEEP_DAYS |
| Rejected rule ideas | Deleted after 90 days | HUNT_RETENTION_REJECTED_IDEA_DAYS |
| Deployment profiles | Newest 10 kept | HUNT_RETENTION_PROFILES_KEEP |
| Disabled runners | Deleted after 180 days without contact | HUNT_RETENTION_RUNNER_IDLE_DAYS |
| Dormant campaigns | Closed after 90 days (0 means never) | HUNT_RETENTION_CAMPAIGN_DORMANT_DAYS |
nano never deletes:
- promoted findings, even after their case is deleted;
- findings that nobody has triaged yet;
- findings that support a rule idea that isn't rejected;
- the newest run of each hunt, or a run that still has findings.
To turn cleanup off, set HUNT_RETENTION_ENABLED=false.
Hunts never delete event data. Events age out with your normal event retention. If a finding's events have aged out, the finding says so.
Grant permissions
Hunt permissions are separate from playbook permissions. Deciding what runs on its own against all your data is a different responsibility from editing response procedures.
| Permission | Allows | Admin | Editor | ReadOnly |
|---|---|---|---|---|
hunts:view | View hunts, runs, findings, memory, campaigns, rulings, the profile, and runners | Yes | Yes | No |
hunts:run | Run a hunt now, change its schedule, and enable or disable it | Yes | Yes | No |
hunts:triage | Promote and dismiss findings, record rulings, link findings to campaigns, and acknowledge escalations | Yes | Yes | No |
hunts:manage | Create, edit, and archive hunts and campaigns, change escalation settings, request reviews, and act on rule ideas | Yes | No | No |
hunts:report | Report run results. Used by a runner's key. | Yes | No | No |
hunts:profile_write | Save a deployment profile and create draft hunts. Used by a profiling key. | Yes | No | No |
Promoting a finding also needs cases:create. Acknowledging an escalation also needs cases:edit.
The ReadOnly role has no hunt permissions, because every new user gets it through the Everyone group. To give read-only access to hunts, add hunts:view to a custom role. See Access control.
Users must sign in again after you change their roles.
What's next
Hunt security
Understand how hunts keep AI agents read-only and limited, handle attacker-controlled log content, keep findings visible, and what data goes to your AI provider.
Troubleshoot hunts
Find out why a hunt didn't run or didn't finish: no_coverage, budget_exhausted, an unavailable server runner, a run waiting for a runner, reasoning effort, and missing reviews.