Quickstart

1. Install the CLI#

The pagr CLI and the daemon it manages are one package, @pagr/cli. Install it globally.

$npm i -g @pagr/cli

Confirm it is on your PATH:

$pagr --version0.1.0

2. Pair this Mac#

pagr connect generates an Ed25519 keypair, stores the private half in your macOS Keychain, sends only the public half to Pagr, and prints a short-lived pairing code. It opens your browser at the same time.

$pagr connect✓ device key ready (keyring; public key 8Jq3nL2vR9xK…)   Pairing code  7K4M9Q  Open          https://app.pagr.dev/pair?code=7K4M9Q  expires 2026-08-25T18:41:07.220Z ✓ paired as dev_9c1f4a72e0b84d3fa6512c8ee7d40b19 (user usr_4a2…)✓ daemon installed /Users/you/Library/LaunchAgents/dev.pagr.bridge.plist Next steps  1. pagr project add . --name MyApp   register a repo (only the id + name leave this Mac)  2. Link iMessage from the dashboard (Settings → Messaging)  3. pagr status                        confirm the gateway is connected

Approve the request in the browser and the CLI finishes on its own. It also installs a launchd agent labelled dev.pagr.bridge, so the daemon starts at login and survives reboots. Pass --no-daemon to skip that and run pagr daemon run in the foreground instead.

3. Register a project#

The bridge can only touch folders you have registered. Register each repository you want reachable, with a name you will actually use in a text message.

$cd ~/code/checkout-api$pagr project add . --name checkout-api --alias checkout,api✓ registered checkout-api as proj_1b7e05c93d6a4f2e8c04b7a91f3d2e56  /Users/you/code/checkout-api  the cloud was told the id + name (never the path)

List what is registered at any time:

$pagr projectsID                                     NAME            ALIASES        PATHproj_1b7e05c93d6a4f2e8c04b7a91f3d2e56  checkout-api    checkout, api  /Users/you/code/checkout-api

The path column comes from your own machine. The cloud only ever learns the id, the display name, the aliases, and — if the folder is a git repository — the remote host and repository name. See projects and path containment.

4. Connect your agents#

There is nothing to configure. The bridge detects Claude Code and Codex by running claude --version and codex --version, and reports whether each is installed and authenticated.

Check the whole picture at once:

$pagr statusPagr bridge  device    dev_9c1f4a7… studio  user      usr_4a2b8c1…  gateway   ✓ connected  daemon    ✓ running (pid 5142, v0.1.0)  projects  1  sessions  0 (0 pending approvals) Agents  claude  ✓ 2.1.220 (cli-hooks, auth unknown)  codex   ✓ 0.9.4 (app-server, auth unknown)

5. Link iMessage#

In the dashboard, open Link iMessage. It shows a single-use code that expires in under ten minutes:

CONNECT 7K4M9Q

Text exactly that to the Pagr number shown on the same page, from the phone whose number is verified on your account. You get a welcome message back, and that phone becomes the only sender Pagr will accept for your account. Messages from any other number are ignored, not answered.

6. Text your agents#

Now put the Mac down.

The full set of phrasings, and what each one actually does, is in texting your agents.

If something is wrong#

pagr doctor checks Node, the permissions on ~/.pagr, the secret store, pairing, the daemon socket, gateway reachability, both agent CLIs and the launch agent — and prints a fix for every failure.

$pagr doctorpagr doctor✓ node           v22.14.0✓ pagr home      /Users/you/.pagr (700)✓ secret store   keyring✓ paired         dev_9c1f4a72e0b84d3fa6512c8ee7d40b19 (studio)✓ daemon         pid 5142, transport connected✓ gateway        gateway.pagr.dev:443✓ codex          codex-cli 0.9.4✓ claude         2.1.220 (Claude Code)✓ launch agent   loaded ✓ all checks passed

It exits 5 when any check fails, so it drops straight into a script. If something is still off, troubleshooting has the symptom table.