Sign in
internal
Daemons

Provision a daemon, or re-provision an existing one

Creates a daemon record on the server before the daemon is installed, mints an API key bound to it 1:1, and returns ready-to-run install artifacts.

When daemon_id is supplied the existing record is reused instead of creating a new one — this both re-issues install artifacts after install config changes and gives a legacy daemon (one with no bound key) a pathway to a dedicated key without losing its host, discovery jobs, or history.

Returns the daemon record and an API key that must be configured on the daemon.

post/api/v1/daemons/provision

Request body

daemon_idstring 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.

namestring nullable

Human-readable name for the daemon. Required unless daemon_id is set, in which case the existing record's name is kept.

network_idstring 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.

urlstring nullable

Reachable URL where the server can dial the daemon. Required for ServerPoll, unused for DaemonPoll (the daemon dials out instead).

Response

Daemon provisioned successfully

errorstring nullable

Human-readable failure message. Omitted on success.

successboolean required

true when the request succeeded. false responses carry error instead of data.

Example response

{
  "data": {
    "daemon": {
      "url": "https://daemon.example.com:60073",
      "version": "0.17.7"
    }
  },
  "meta": {
    "api_version": 1,
    "server_version": "0.17.7"
  }
}

Changes