Log inGet started

Pairing

Generate a dashboard pairing code and enter it on the machine. Codes last about three minutes and work once.

What this is

Pairing is the only machine-to-account link. The website generates a short code; you type it on the host. Do not put your account password or an AppSumo code into the agent.

Pairing code flow
Pairing code flow

Prerequisites

  • PortPilot installed and portpilot status healthy
  • Signed-in account with a free seat (Licensing)
  • Outbound HTTPS from the host to https://api.portpilot.app

Official workflow

  1. Log in at portpilot.app.
  2. Open Machines.
  3. Choose Add machine.
  4. Choose Generate pairing code.
  5. Keep the code visible (countdown is about three minutes).
  6. On the target machine: Desktop Enter pairing code, or portpilot pair.
  7. Wait until the dialog shows Machine paired successfully.
  8. The machine appears in the dashboard — View machine.

Letters O/0 and I/1 are treated the same. Creating a new code expires any unused code you still had open.

The agent opens an outbound WebSocket. Browsers never talk to the privileged agent.

Expected result

  • Dialog: Machine paired successfully
  • Desktop: Machine paired / status Paired, Cloud connected
  • Website: host online with ports filling in
  • Entitlements arrive with the cloud handshake and cache locally for 24 hours offline

What happens otherwise

SituationResultWhat to do
Code expiresClaim fails as expiredGenerate a new code
Invalid codeClaim failsCheck hyphens; O/0 and I/1 match; do not use an AppSumo code
Code already usedClaim fails as usedGenerate a new code
Machine already pairedLocal enrollment already setUnpair locally or revoke in the dashboard, then pair again
Seat fullmachine_limit_reachedRevoke a machine or upgrade
Wrong accountMachine appears on the other loginSign into the account that generated the code

Pairing troubleshooting

Invalid code

You typed a dashboard pairing code, not a licence/AppSumo string. Re-copy from Your pairing code. Crockford encoding treats O/0 and I/1 as the same.

Expired code

Codes last about 180 seconds. Generate a new one and pair immediately. Keep the Add a machine dialog open.

Code already used

Each code works once. Generate a new code even if you are pairing the same host again.

Machine already paired

Desktop Machine shows Paired. portpilot unpair or Unpair locally clears local enrollment only — Revoke in the dashboard if you need the seat freed. The same machine id after revoke reuses the seat.

Network failure

The host must reach https://api.portpilot.app outbound. Proxies and captive portals will fail claim. portpilot doctor reports cloud reachability.

Machine does not appear online

  1. Identify the machine in Machines (or confirm it never registered).
  2. On the host: Windows Get-Service PortPilotAgent; Linux systemctl status portpilot-agent.
  3. portpilot status / portpilot doctor.
  4. Check last seen on the website.
  5. Logs: Windows %ProgramData%\PortPilot\logs\; Linux journalctl -u portpilot-agent.service -n 80.

Wrong account

The machine belongs to the account that generated the successful code. Sign in there. Licences are not transferable; support will not ask for your password.

Unpair locally with portpilot unpair or revoke in Machines. Revoke frees the seat immediately.

Download PortPilot · FAQ · Support