This page covers both the free and Pro tiers. If you only want to run one check, the first section is enough.
One-off check (free tier)
Windows: the peira.exe you downloaded is the program itself — nothing to unzip, nothing to install. Double-click it to open the desktop window; the top right switches between 繁體中文 / English / 日本語.
For a complete verdict, right-click and choose "Run as administrator". Without elevation Peira cannot read firewall rules, so kill-switch checks report "cannot determine" rather than a conclusion.
Linux: unpack the tarball and run ./peira. Adding ui opens the local web interface (bound to 127.0.0.1 only, with a one-time token in the URL).
Common flags
| Flag | Purpose |
|---|---|
--lang zh\|en\|ja |
Report language |
--json |
JSON output for programs |
--list |
List every check |
--only tunnel,dns |
Run only the named checks |
--egress |
Enable egress verification (the only feature that goes online) |
--expect-org M247 |
Declare the expected exit organization; a mismatch counts as a leak |
Apart from --egress, Peira contacts no servers. Every address it did contact is listed at the end of the report.
Pro tier
The desktop app has a Protection monitoring panel. This section covers the panel first, then the command line. Both drive the same machinery and share the same settings.
Activating a licence
Desktop: click the tier badge in the top right and paste your key.
Command line:
peira license activate PEIRA-...
peira license
The second line shows the current state. Licences are verified offline: no connection, no account.
Continuous monitoring
From the desktop app (recommended)
The Protection monitoring section on the main screen:
- Click Start monitoring. The status line shows that it is running, since when, and how many checks it has done.
- Alert URL takes a webhook (an ntfy topic URL, for instance). Leave it empty for no alerts.
- Alert threshold decides how serious something must be before you are told. Press Save settings and monitoring restarts to pick up the change.
- Tick Start at login to keep monitoring while the app is not open.
⚠️ The panel's monitor runs with the window and stops when you close it. To monitor in the background you must also tick Start at login — they are two different things.
When the state changes, the panel offers to reload so the report above is refreshed. It never reloads on its own, because you may be in the middle of reading.
From the command line
peira --watch
It keeps running and re-checks the moment it detects the network state change — switching Wi-Fi, a VPN reconnect, waking from sleep. A fixed interval misses that window, so change detection is the default behaviour rather than an extra option.
| Flag | Default | Purpose |
|---|---|---|
--interval |
5m | Full re-check interval |
--change-interval |
10s | How often network state is polled for changes |
--webhook URL |
— | POST the event JSON when the state changes |
--notify-cmd PATH |
— | Run a program on change; the event JSON arrives on stdin |
--notify-on |
warn | Alert threshold: critical / warn / unknown |
--alert-cooldown |
5m | Cooldown for repeated alerts |
--history PATH |
— | Append a summary of every check to this JSONL file |
Alerts fire only when the state gets worse and reaches the threshold, or when a problem is resolved. Resolutions are sent too — otherwise you would keep assuming you are still leaking.
Networks flap for a few seconds while switching, which is what the cooldown is for. Without it you would get ten notifications in half a minute and then turn notifications off.
Starting automatically at login
The checkbox in the panel does exactly what follows; the command line simply lets you pass extra flags.
peira service install --watch --egress --webhook https://ntfy.example/peira
peira service status
peira service uninstall
install records whatever monitoring flags you pass on that line.
- Windows: creates a Task Scheduler task that runs at logon. It is deliberately not a Windows service: a real service needs administrator rights to install and, running in Session 0, cannot see your network environment.
- Linux: installs a user-level systemd unit (
~/.config/systemd/user/), never a system one. ⚠️ User units stop at logout by default. To keep monitoring while logged out, enable lingering:loginctl enable-linger $USER.
Both run after login, tied to your user session — this is not a system-level resident service.
Event format
The webhook and --notify-cmd receive the same JSON: hostname, time, worst severity, and the lists of new and resolved findings. Each --history line is a summary (time, trigger reason, worst severity, counts per level), ready to feed to a plotting tool.
Verifying your download
sha256sum -c SHA256SUMS --ignore-missing
To also confirm the checksum file itself was not replaced:
curl -O https://odysec.org/pgp-key.txt
gpg --import pgp-key.txt
gpg --verify SHA256SUMS.asc SHA256SUMS
Key fingerprint: 1360 6273 6DFC 9D4B C9A1 5312 6FD4 6C88 46C0 DA1B
Updating
Desktop: Help → Check for updates. Command line:
peira --check-update
peira --update
The update replaces the executable in place and restarts automatically. The filename does not change.