Reference

Configuration

Almost nothing needs configuring to use Pagr. This page exists for the cases that do: pointing the bridge at a local stack, running it headless, and understanding what the hosted side is set to.

Bridge environment#

These are read by the pagr CLI and the daemon on your Mac. The launch agent captures PAGR_HOME and PATH at install time, so changing either means re-running pagr daemon install.

Bridge environment variables
Variable	Value	Effect
`PAGR_HOME`	`path`	Where local state lives. Default ~/.pagr.
`PAGR_API_URL`	`url`	API base URL for pairing. Default https://api.pagr.dev.
`PAGR_WEB_URL`	`url`	Dashboard base URL used by `billing` and `logout`. Default https://app.pagr.dev.
`PAGR_LOG_LEVEL`	`debug`	Raises the daemon log level. Anything else is treated as info.
`PAGR_DEBUG`	`1`	Prints stack traces on unexpected CLI errors.
`PAGR_MOCK_AGENTS`	`1`	Runs scripted mock agents instead of real ones — same as `pagr daemon run --mock`.
`PAGR_MOCK_AGENT_DELAY_MS`	`ms`	Stretches the scripted mock turns. Used by the end-to-end tests.
`PAGR_INSECURE_FILE_STORE`	`1`	Stores the device private key in ~/.pagr/secrets.json instead of the Keychain. For CI and headless machines only; the daemon warns whenever it is set.
`PAGR_CLAUDE_CHANNEL`	`1`	Enables the flagged Claude Code channel path. Off by default.
`PAGR_CHANNEL_SERVER`	`path`	Overrides the resolved path to the Pagr channel server for `claude channel-setup`.

Most flags have an equivalent: --home for PAGR_HOME, --api-url for PAGR_API_URL, --web-url for PAGR_WEB_URL, --mock for PAGR_MOCK_AGENTS. The flag always wins.

$# point a throwaway bridge at a local stack$PAGR_HOME=/tmp/pagr-dev pagr connect \$  --api-url http://localhost:4000 \$  --gateway-url ws://localhost:4001 \$  --no-daemon

Files under ~/.pagr#

The directory is created mode 0700 and holds everything local. Nothing here is uploaded.

Local state files
Path	Contents
`config.json`	Device id, user id, gateway URL, API URL, pinned server public keys, device name, paired-at timestamp. No secrets.
`projects.json`	Project id to local path, aliases, and the git repository hint.
`sessions.json`	Session id to provider session id.
`replay.json`	Recently seen command nonces, persisted best-effort.
`policy.json`	The approval policy synced from your dashboard settings.
`logs/daemon.log`	JSON lines, with your home directory rewritten to `~`.
`run/daemon.sock`	The local Unix socket, mode `0600`.
`tmp/att_*`	Downloaded images, deleted immediately after use and swept after 24 hours.

Control-plane environment#

You do not set these — Pagr runs the hosted side — but the names are worth knowing because they are what the numbers quoted elsewhere in these docs come from. Every service validates its environment once at boot and fails fast with a readable list rather than a stack trace deep in a request.

Control-plane settings referenced in these docs
Variable	Default	What it controls
`QUEUED_COMMAND_TTL_HOURS`	`12`	How long a command waits for an offline Mac before it is dropped.
`ATTACHMENT_TTL_HOURS`	`24`	How long a stored screenshot lives.
`MESSAGE_RETENTION_DAYS`	`30`	How long message history is kept.
`APPROVAL_LINK_TTL_SECONDS`	`900`	How long a step-up link stays valid — capped by the approval's own expiry. Only relevant to users who have turned Approve high-risk actions by text off; with it on, no link is minted.
`DEVICE_TOKEN_TTL_SECONDS`	`900`	Device token lifetime.
`PAGR_MIN_BRIDGE_VERSION`	`0.0.0`	The minimum bridge version the gateway will accept; an older bridge stops reconnecting and asks to be updated.

Provider selectors#

The control plane picks each third-party provider independently, which is what lets the whole product run locally with no keys at all:

.env

MESSAGING_PROVIDER=sendblue   # mock | sendblueLLM_PROVIDER=openai           # mock | openaiBILLING_PROVIDER=stripe       # mock | stripeAUTH_PROVIDER=clerk           # mock | clerk

Commercial constants#

Prices and trial length are configuration, not constants scattered through the code — which is why the numbers on this site and in the product always agree.

Commercial configuration
Variable	Default
`TRIAL_DAYS`	7
`STANDARD_PRICE_USD`	29

What those numbers mean commercially is in billing.