Installation & operation

Enroll a device on your account

Enrollment is the one-time step that binds a device to your account. The install code is the primary path: create it in the panel, pass it to the installer, and the daemon exchanges it with the backend for a saved credential, which it reuses from then on. The backend assigns the device its identity at redemption, so one code can enroll several devices. The legacy per-device flow, an app ID plus a matching single-use code, still works unchanged. This page covers both.

~7 min read · Installation & operation

The install code

Create an install code in the panel, under Install keys. It is shown once, so copy it right away, then pass it to the installer as an environment variable:

VariablePurpose
PZ_ENROLL_CODEThe install code from the panel. On its own it is enough for a fresh enrollment.
PZ_APP_IDLegacy and optional: only needed together with an older per-device code (see below).
bashTerminal
curl -fsSL https://poisonzero.com/install.sh | sudo \
  PZ_ENROLL_CODE="your-install-code" sh
An install code is multi-use: it enrolls devices up to the redemption cap you set when you create it, and every successful enroll counts against that cap. Revoke it in the panel at any time to stop further redemptions; devices already enrolled through it keep working.

What the installer writes

The installer drops a small enroll file, then runs the daemon's enroll command. The daemon writes the credential it will reuse from then on:

FileLocationContents
enrollConfig dir (Linux /etc/poisonzero, macOS Application Support, Windows ProgramData)JSON { code }, plus appId for the legacy pairing; mode 0600, consumed once at enroll
credentialsData dir (Linux /var/lib/poisonzero, macOS Application Support, Windows ProgramData)The device identity and a refresh token, assigned by the backend at redemption; reused across restarts
license.idData dirThe Enterprise device binding (seat); absent on Pro
The presence of the credentials file is what marks a device already enrolled. A plain upgrade that finds it skips enrollment and only swaps the binary.

The enroll command

poisonzero enroll takes no flags; it reads the enroll file and drives the exchange:

  1. Reads the enroll file and requires the install code; an app ID, if present, is sent alongside it for the legacy pairing.
  2. Posts the code, the app ID (if given), platform and version to the backend enroll endpoint.
  3. On success, the backend assigns the device its identity; the daemon exchanges the returned token for a refresh token and writes it to credentials.
  4. Persists the device mode (cloud or private) and, on Enterprise, the license id.
The backend validates the code before anything is written: it must exist, still be under its redemption cap (or unused, for a legacy code), and not be expired or revoked. A used-up, revoked or expired code is refused.

Redemptions, seats and licenses

Two limits apply independently: how many times a code can be redeemed, and how many devices your account allows:

ConceptMeaning
Redemption capThe maximum number of devices one install code can enroll, set when you create it in the panel
Legacy codeTied to a single app; marked used after the first successful enroll, exactly as before
Seat / device slotEach enrolled device counts against your account's device limit, whichever code enrolled it
Pro device limitPro accounts are capped at a fixed number of active devices; enrolling past the limit is refused with a device-limit error
License idEnterprise devices carry a license id (license.id); Pro devices carry none
Re-enrolling a device that is already active does not consume an additional seat or an additional redemption.

The legacy per-device flow

Creating a device in the panel still works exactly as before, for older installers or scripted integrations that expect an app ID:

  • Creating a device in the panel mints an app ID and a matching single-use code.
  • Pass both to the installer: PZ_APP_ID and PZ_ENROLL_CODE.
  • The code is tied to that one app and is marked used after the first successful enroll.

Re-enrolling

Running the installer again with a fresh install code re-enrolls the device cleanly:

ModeTriggerEffect
FreshNo credentials fileEnrolls for the first time
Re-enrollcredentials present and a new PZ_ENROLL_CODE is passedReplaces the credential cleanly; on failure the old credential is kept
Upgradecredentials present, no PZ_ENROLL_CODESwaps the binary only; enrollment is skipped
PZ_ENROLL_CODE is required to re-enroll. PZ_APP_ID on its own, with no code, is ignored and the run is treated as a plain upgrade.
bashTerminal
curl -fsSL https://poisonzero.com/install.sh | sudo \
  PZ_ENROLL_CODE="a-fresh-code" sh
powershellPowerShell
$env:PZ_ENROLL_CODE="a-fresh-code"
iwr https://poisonzero.com/install.ps1 -UseBasicParsing | iex

Where the code is used at rollout: installing PoisonZero. What cloud versus private changes after enroll: cloud or private. Provision a fleet without hands: the management API.

Was this helpful?

An install code binds a device to your account.

Create it once in the panel, run one command, and enroll every device that code allows. Free for Linux, macOS and Windows.

Sign me up

Related articles

Installation & operationInstalling PoisonZero: complete referenceOperating modesCloud or private: choosing a modeConsole & fleetManagement API