---
title: "Provision a daemon, or re-provision an existing one"
method: POST
path: "/api/v1/daemons/provision"
tags: ["Daemons"]
---

# Provision a daemon, or re-provision an existing one

`POST /api/v1/daemons/provision`

Creates a daemon record on the server before the daemon is installed and mints an API key
bound to it 1:1. Returns the daemon record and that key, which is shown only once and must
be configured on the daemon.

When `daemon_id` is supplied the existing record is reused instead of creating a new one,
giving a legacy daemon (one with no bound key) a pathway to a dedicated key without losing
its host, discovery jobs, or history. Re-provisioning always mints a fresh key.

Install commands are not built here — fetch them from the install-command endpoint, which
builds them idempotently and fills in the key this returns. That keeps a display-only
regenerate (an OS switch, an advanced-setting change) from re-minting the key.

## Request body

- ProvisionDaemonRequest — Request to pre-provision a daemon (either mode) before it is installed. This creates the daemon record + its 1:1 API key on the server so the install command shrinks to two flags.
  - `daemon_id` string, uuid, nullable — Mint a fresh 1:1 key for this existing daemon instead of creating a new record, keeping its host, discovery jobs and history. Used to give a legacy daemon (no bound key) a dedicated one. When set, `name`/`network_id`/`mode`/`url` are ignored — those come from the existing record. Only accepted for a daemon that has never checked in or has no bound key; a live provisioned daemon is refused, since it has no way to learn the new key. Note: install commands are not generated here — call the install-command endpoint, which builds them idempotently and fills in the key this response returns.
  - `mode` 'server_poll' | 'daemon_poll' — Daemon operating mode that determines the communication pattern. - **DaemonPoll** (formerly "Pull"): Daemon makes outbound connections to the server. The daemon registers itself and polls for work. Best for daemons behind NAT/firewall. - **ServerPoll** (formerly "Push"): Server makes connections to the daemon. Server polls daemon for status and discovery results. Best for DMZ deployments where daemon cannot make outbound connections.
  - `name` string, nullable — Human-readable name for the daemon. Required unless `daemon_id` is set, in which case the existing record's name is kept.
  - `network_id` string, uuid, nullable — Network this daemon will be associated with. Required unless `daemon_id` is set, in which case the existing record's network is kept.
  - `seed_credential_refs` IntegrationTarget[] — Credential/integration references to seed onto the daemon's first discovery run. References only — never secret material. Empty by default.
    - union — Per-daemon integration targeting, stored on the `Discovery` entity and delivered via the init command at registration. Each entry references exactly one stored credential and says where it applies on this daemon. This is the single home for cred↔IP targeting — it replaces the global, race-prone `credential.target_ips`. The variants ARE the scopes; their strum [`Target`] discriminants are the capability enum that `CredentialType::targets()` returns and validates against (single source of truth). Every target carries a real `credential_id` — there is no credential-less branch and no nil sentinel; a local socket is just a credential whose type targets only the daemon host.
      - object — The daemon's own host — realized as a 127.0.0.1 IP-override (e.g. a local Docker/Podman socket, or any credential the user pins to the daemon host without naming its IP).
        - `credential_id` string, uuid, required — Credential to use on the daemon host.
        - `scope` 'DaemonHost', required
      - object — All hosts on the network — a broadcast default credential.
        - `credential_id` string, uuid, required — Credential to use across the network.
        - `scope` 'Network', required
      - object — Specific host IPs — one IP-override per address.
        - `credential_id` string, uuid, required — Credential to use on the listed addresses.
        - `ips` string[], required — The host addresses this credential applies to.
        - `scope` 'Hosts', required
  - `url` string, nullable — Reachable URL where the *server* can dial the daemon. Required for ServerPoll, unused for DaemonPoll (the daemon dials out instead).

## Response `201`

Daemon provisioned successfully

- ApiResponseProvisionDaemonResponse
  - `data` object — Response from provisioning a daemon. Contains the daemon record and the API key (shown only once). Install commands are deliberately not here — fetch them from the install-command endpoint, which builds them idempotently and fills in this key. That keeps a display-only regenerate (advanced-setting change, OS switch) from re-minting the key.
    - `daemon` DaemonResponse, required — Daemon response for UI including computed version status
      - `api_key_id` string, uuid, nullable — Foreign key to API key used for ServerPoll authentication. NULL for DaemonPoll daemons or those not yet linked to a key.
      - `host_id` string, uuid, required — The host this entity belongs to.
      - `is_unreachable` boolean — Whether the daemon is unreachable (for ServerPoll circuit breaker). Set to true after repeated polling failures, reset via retry-connection endpoint.
      - `last_seen` string, date-time, nullable — Timestamp of last successful contact with daemon. NULL for provisioned ServerPoll daemons that haven't been contacted yet.
      - `mode` 'server_poll' | 'daemon_poll', required — Daemon operating mode that determines the communication pattern. - **DaemonPoll** (formerly "Pull"): Daemon makes outbound connections to the server. The daemon registers itself and polls for work. Best for daemons behind NAT/firewall. - **ServerPoll** (formerly "Push"): Server makes connections to the daemon. Server polls daemon for status and discovery results. Best for DMZ deployments where daemon cannot make outbound connections.
      - `name` string, required — Human-facing name for this daemon.
      - `network_id` string, uuid, required — The network this entity belongs to.
      - `standby` boolean — Whether the daemon is on standby due to inactivity (no discovery in 30 days).
      - `standby_cleared_at` string, date-time, nullable — Timestamp of the most recent standby → active transition. Set by `process_startup` when a restarted daemon is un-standby'd, and by the discovery auto-wake path. The nightly inactivity check skips daemons within the grace window (see `STANDBY_GRACE_PERIOD_DAYS`) to prevent the "restart → cleared → re-standby'd before discovery runs" race.
      - `tags` string[], required — Tags assigned to this entity.
      - `url` string, uri, required — Address the *server* dials for a ServerPoll daemon. Editable (a daemon can move); unused and not editable for DaemonPoll, which dials out instead. Base URL the server reaches this daemon on.
      - `user_id` string, uuid, required — User responsible for maintaining this daemon
      - `version` string, nullable — Daemon software version (semver format)
      - `created_at` string, date-time, required — When this record was first created.
      - `id` string, uuid, required — Server-assigned unique identifier.
      - `interfaced_subnet_ids` string[], required — Subnets this daemon has interfaces on, loaded from the `daemon_interfaced_subnets` junction (replaces the old `capabilities.interfaced_subnet_ids` JSONB field).
      - `updated_at` string, date-time, required — When this record was last modified.
      - `version_status` DaemonVersionStatus, required — Daemon version status including health and any warnings
        - `has_correct_docker_volume_mount` boolean — Whether a containerized daemon is mounted so it can read the Docker socket.
        - `status` 'Current' | 'Outdated' | 'Deprecated' | 'Unsupported' | 'Unknown', required — Health status for daemon versions. Lifecycle order: `Current` → `Outdated` → `Deprecated` → `Unsupported`, with `Unknown` for daemons whose version the server has no record of.
        - `sunset_date` string, nullable — The date this daemon's version stops being supported, if a sunset is scheduled for it. Surfaced top-level (not only inside `warnings`) so the UI can render a countdown from the same value the email uses.
        - `supports_targeted_rescan` boolean — Whether this daemon can run a single-host rescan. Server-computed so the frontend never has to hardcode a version floor.
        - `supports_unified_discovery` boolean — Whether the daemon can run a combined discovery pass.
        - `version` string, nullable — Version the daemon reports.
        - `warnings` DeprecationWarning[] — Upgrade warnings that apply to this version.
          - `message` string, required — What the operator needs to do, and by when.
          - `severity` 'Info' | 'Warning' | 'Critical' | 'Unknown', required — Severity level for deprecation warnings
          - `sunset_date` string, nullable — Date after which this daemon version stops being supported.
    - `daemon_api_key` string, password, required — The API key (plaintext) for daemon authentication. This is shown only once - store it securely.
  - `error` string, nullable — Human-readable failure message. Omitted on success.
  - `meta` ApiMeta, required — API metadata included in all responses
    - `api_version` integer, required — API version (integer, increments on breaking changes)
    - `server_version` string, required — Server version (semver)
  - `success` boolean, required — `true` when the request succeeded. `false` responses carry `error` instead of `data`.

## Other responses

- `400` — Invalid request
- `403` — Forbidden
- `409` — Daemon is live and already has a bound key

---

[API](https://skmtc.net/scanopy/apis/scanopy-api.md) · [All operations](https://skmtc.net/scanopy/apis/scanopy-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scanopy/scanopy-api/revisions/2df1fc47dfa7/schema)