Docs Guides
Roll out with device management
To put Phigon on many company computers at once, use an enrollment code (phe_…) instead of one pairing code per computer. Your device management tool (Microsoft Intune, Jamf Pro, or Ansible, Puppet or Salt on Linux) runs a short script on each computer, and each computer connects to your Phigon by itself.
Enrollment codes need observer 8.3.0 or newer. Pin the version you tested in every script.
What an enrollment code means
With an enrollment code, your company gives consent for its computers, and nobody at the computer is asked. You choose what Phigon collects for every computer that uses the code: Agents only (metadata) or Everything (full activity). Phigon records that the company consented, names the code, and shows it for each computer.
- Employees are told. When the observer starts collecting on an enrolled computer, the person signed in gets a system notification once: "Phigon is recording AI agent activity", what it records, the code's name, and "Ask your IT team for details". They are told again if the profile changes.
- Administrators may stop agents and run the commands they approve on enrolled computers, under the company's consent. The person at the computer gets a notification each time. Add
--remote-actions stop-agents(only stopping agents) or--remote-actions noneto the pair command to allow less. - Tell people first. The notification is a reminder, not the notice the law may require: it appears only once the observer runs, it can be turned off, and it can't show without the person's desktop session. Give employees the employee privacy notice before you roll out, and check that your policy meets the law where they work.
Name the code after something people will recognise, such as "Acme engineering laptops": the name appears in the notification.
1. Create a code
In the Phigon app, choose Connect machine, then Many computers:
- Name: what employees will see in the notification.
- How many computers: close to the size of the rollout (1 to 10,000).
- Valid for (days): the length of the rollout, at most 30 days. The default is 7.
- What Phigon collects: Agents only or Everything.
Choose Create code. Phigon shows the code once, with the install script for Windows, macOS and Linux and your server's addresses already filled in. Copy it straight into your device management tool's secret storage. Don't paste the code into tickets, chat or source control: whoever holds it can enroll computers until it expires, runs out or is revoked.
Computers on any network can enroll: the script uses Phigon's relay addresses, with your server's certificate fingerprint (--server-ca-sha256), which each computer pins. If some computers can't reach the internet, turn on Settings › Computers on this network and choose Office network only for their script. Read about computers on any network.
2. What every install does
On each computer, the script:
- Installs the observer:
npm install --global @phigon/observer@<version>. Node.js 24.5 or newer must be there first; install it with its own package in your tool. - Enrolls the computer as the person who uses it, with the code in the
PHIGON_ENROLLMENT_CODEenvironment variable, never on a command line others can see. The observer never prints, logs or saves the code. - Runs the observer in the background whenever that person is signed in:
phigon-observer service install.
Run the enrollment as the signed-in person, not as SYSTEM or root: the observer finds AI agents in that person's home folder and keeps its key in their data folder.
The pair command for a server reached through the relay looks like this:
PHIGON_ENROLLMENT_CODE="$(cat /path/to/code)" phigon-observer pair \
--control-plane-url https://<label>.relay.phigon.online \
--grpc-url https://<label>-grpc.relay.phigon.online \
--server-ca-sha256 <fingerprint> --json
phigon-observer service install
With an enrollment code, pair asks nothing, and --consent-profile and --accept-consent are refused. A misspelled or unknown option stops it with exit code 2 before anything is sent. A busy server is asked again up to three times, within five minutes.
3. Add it to your tool
Windows with Intune
Use two Win32 apps:
- Node.js 24 (the official MSI), install behavior System.
- Phigon observer, install behavior User, with Node.js as its dependency. Package the install script from the app as
install-phigon.ps1.
The script from the app looks like this, with your values:
# Runs as the signed-in user: an Intune Win32 app with install behavior User.
$ErrorActionPreference = 'Stop'
$version = '8.12.0' # pin the observer version you tested
$controlPlane = 'https://<label>.relay.phigon.online'
$grpc = 'https://<label>-grpc.relay.phigon.online'
$fingerprint = '<fingerprint>'
npm install --global "@phigon/observer@$version"
if ($LASTEXITCODE -ne 0) { exit 1 }
$observer = Join-Path $env:APPDATA 'npm\phigon-observer.cmd'
# The code goes to the observer in its environment, never on a command line.
$env:PHIGON_ENROLLMENT_CODE = '<the code>'
$pair = @('pair', '--control-plane-url', $controlPlane, '--grpc-url', $grpc, '--json')
if ($fingerprint) { $pair += @('--server-ca-sha256', $fingerprint) }
try { & $observer @pair; $enrolled = $LASTEXITCODE }
finally { Remove-Item Env:PHIGON_ENROLLMENT_CODE -ErrorAction SilentlyContinue }
# Pass pair's exit code on (20 retry later, 21 new code needed, ...).
if ($enrolled -ne 0) { exit $enrolled }
& $observer service install
exit $LASTEXITCODE
Install command:
powershell.exe -NoProfile -ExecutionPolicy Bypass -File install-phigon.ps1Detection rule (a custom script, run as the user):
$observer = Join-Path $env:APPDATA 'npm\phigon-observer.cmd' if (-not (Test-Path $observer)) { exit 1 } & $observer doctor --check --max-delivery-age 60 | Out-Null if ($LASTEXITCODE -eq 0) { Write-Output 'Phigon observer is enrolled and sending'; exit 0 } exit 1Uninstall command: run
phigon-observer remove-machine --purge --yes --jsonas the user, thennpm uninstall --global @phigon/observer. Collection stops and the computer's key is revoked; its history stays until you delete the computer in Phigon.
Intune keeps the package encrypted, but anyone who can edit the app in Intune can read the code, so keep the code short-lived.
macOS with Jamf Pro
Install Node.js 24 with its own policy (the official .pkg). Then add the script from the app to a policy that runs at login. Jamf runs scripts as root; the script installs the observer for everyone and enrolls the person signed in.
#!/bin/sh
# Jamf runs this as root; it enrolls the person signed in.
version="8.12.0" # pin the observer version you tested
code='<the code>'
control_plane='https://<label>.relay.phigon.online'
grpc='https://<label>-grpc.relay.phigon.online'
fingerprint='<fingerprint>'
user=$(stat -f %Su /dev/console)
if [ -z "$user" ] || [ "$user" = root ] || [ "$user" = loginwindow ]; then
echo "Nobody is signed in. Run this policy at login."
exit 1
fi
uid=$(id -u "$user")
/usr/local/bin/npm install --global "@phigon/observer@$version" || exit 1
set -- pair --control-plane-url "$control_plane" --grpc-url "$grpc" --json
[ -n "$fingerprint" ] && set -- "$@" --server-ca-sha256 "$fingerprint"
# The code goes to the observer in its environment, never on its command line.
PHIGON_ENROLLMENT_CODE="$code" launchctl asuser "$uid" \
sudo --preserve-env=PHIGON_ENROLLMENT_CODE -H -u "$user" \
/usr/local/bin/phigon-observer "$@" || exit $?
launchctl asuser "$uid" sudo -H -u "$user" /usr/local/bin/phigon-observer service install
Jamf administrators can read the script, so keep the code short-lived. For an extension attribute, run phigon-observer doctor --json the same way, as the signed-in person, and report its status.
Linux with Ansible, Puppet, Salt or a script
Install Node.js 24 and the observer as root, then enroll as the person. Deliver the code as a file only that person can read, from your secret manager, not in the play or script itself.
# As root:
npm install --global "@phigon/observer@8.12.0"
# As the person who uses the computer:
PHIGON_ENROLLMENT_CODE="$(cat /run/phigon/enrollment-code)" \
phigon-observer pair --control-plane-url https://<label>.relay.phigon.online \
--grpc-url https://<label>-grpc.relay.phigon.online \
--server-ca-sha256 <fingerprint> --json
phigon-observer service install
service install sets up a systemd user unit, which runs while the person is signed in. To keep it running without a session, run loginctl enable-linger <user>.
When enrollment fails
A failed enrollment prints the server's sentence and exits with a code your tool can act on. With --json it also prints {"enrolled": false, "error": {"code": "…", "message": "…"}, "exitCode": …}.
| Exit code | What it means | What to do |
|---|---|---|
2 |
The command line is wrong, for example a misspelled option. | Fix the script. Nothing was sent. |
20 |
The server was busy or out of reach. | Try again later. Up to 60 computers a minute can enroll from one address. |
21 |
The code expired, was revoked or is used up. | Create a new code and update the script's secret. |
22 |
The code is cut short or mistyped. | Copy it again. |
23 |
This computer used this code before and was removed since. | Enroll it with a new code. |
24 |
The computer is already connected to your Phigon. | Nothing to do; check it with doctor. |
1 |
Anything else, such as a bad setting. | Read the sentence. |
4. Check that it works
Run this as the computer's user. It sends no activity and exits with the code of the first problem it finds:
phigon-observer doctor --check
| Exit code | Meaning |
|---|---|
0 |
Enrolled, consent current, running, delivering, server reachable. |
3 |
Not enrolled: the enrollment did not finish. |
4 |
Consent missing or out of date: enroll again with a new code. |
5 |
The observer is not running: check phigon-observer service status. |
6 |
Nothing delivered within --max-delivery-age minutes (default 15). |
7 |
The server could not be reached. |
1 |
The check itself failed. |
For the details, phigon-observer doctor --json shows the profile, who consented (consent.source is company, with the code's name) and the observer version. On a computer that stopped, phigon-observer service status says why and shows the last error from its log, and phigon-observer logs --tail 100 shows what it did.
In the Phigon app, each enrolled computer appears on Agents. The code's list under Connect machine › Many computers shows how many computers it enrolled. A number above your rollout's size means the code reached computers you did not plan for.
After the rollout
- Revoke the code. Computers it enrolled stay connected.
- Delete computers you don't recognise. A deleted computer's key stops working at once.
- For new computers later, create a new code rather than keeping an old one alive.
Every option is in Observer commands.