Running it with npx

permaura is the one-command way to install and run the gateway. It is a thin npx launcher: it downloads the self-contained binary, keeps it current, and runs it.

It is not a second tool. Everything but start and upgrade is handed straight to the binary, so npx -y permaura status and a permaura status typed against an installed copy are the same program. See the CLI for what it can do.

npx -y permaura with no command prints the help and starts nothing. Starting a gateway is always start.

Install and run

# install and start the gateway on 127.0.0.1:7376
npx -y permaura start

# install, start, and connect it to your account in one step
PERMAURA_PAIR_CODE=PGW-XXXXXXXX npx -y permaura start

On Windows the code is set first: $env:PERMAURA_PAIR_CODE = "PGW-XXXXXXXX"; npx -y permaura start in PowerShell, or set "PERMAURA_PAIR_CODE=PGW-XXXXXXXX" && npx -y permaura start in Command Prompt.

The pairing code comes from the console's "Connect a gateway" dialog. Give it in PERMAURA_PAIR_CODE rather than with --pair <code>, which works too but puts the code in the process list, where every local user can read it. Either way there are no tokens to copy: the gateway redeems the code and binds itself to your account. See Connect a gateway for the full onboarding walkthrough.

Options and environment

Flag / variable	Effect
start	fetch or update the binary, then run the gateway
start with PERMAURA_PAIR_CODE set (or --pair <code>)	…and redeem a one-time pairing code to connect it to your account
upgrade	fetch the latest binary and exit, without starting anything
--version	print the launcher's version and the installed binary's
--no-upgrade	run the binary you already have; skip the update check
PERMAURA_ADDR	bind address (default 127.0.0.1:7376)
PERMAURA_API	account API base (default https://permaura.com). From gateway 1.3.51 a release build honors only a loopback address here (http://127.0.0.1:<port>, for a local test stub) and ignores any other value with a warning
PERMAURA_HOME	where the binary, store and operator token live (default ~/.permaura)
PERMAURA_TOKEN	operator bearer to use instead of the one in ~/.permaura/operator.token
PERMAURA_CONSOLE_ORIGINS	browser origins allowed to call the gateway cross-origin. Unset, the hosted console (https://permaura.com, https://www.permaura.com) and the desktop app's webview (tauri://localhost, http://tauri.localhost). A value starting with + adds to those (+http://localhost:3102); any other value is the whole list
PERMAURA_INFISICAL_CLIENT_ID	Infisical machine identity, required by both the static and dynamic backends
PERMAURA_INFISICAL_CLIENT_SECRET	its client secret
PERMAURA_INFISICAL_ENV	Infisical environment slug, e.g. prod
PERMAURA_INFISICAL_URL	Infisical base URL (default https://app.infisical.com). Must be https, except loopback for local development
PERMAURA_INFISICAL_PATH	secret path within the environment (default /)
PERMAURA_INFISICAL_DYNAMIC_SECRETS	secret_id=dynamic-secret-name:FIELD,… mints a short-TTL credential per call (details)
PERMAURA_INFISICAL_DYNAMIC_PROJECT_SLUG	the Infisical project slug those dynamic secrets live in
PERMAURA_INFISICAL_DYNAMIC_TTL	lease TTL, e.g. 5m (default). The backstop if a revoke never lands, not the usual lifetime
PERMAURA_SLACK_WEBHOOK_URL	Slack incoming webhook to post approve/notify events to (details)
PERMAURA_DISCORD_WEBHOOK_URL	Discord incoming webhook for the same events
PERMAURA_BUZZ_RELAY_URL / PERMAURA_BUZZ_PRIVATE_KEY / PERMAURA_BUZZ_CHANNEL	post to a Buzz community via the buzz CLI; give the gateway its own 64-hex identity
PERMAURA_CONSOLE_URL	console those chat links point at (default https://permaura.com)
PERMAURA_BUZZ_AUTH_TAG / PERMAURA_BUZZ_BINARY	Buzz relay attestation, and the CLI path when it is not buzz on PATH
PERMAURA_WORKSPACE_ID	workspace those links switch to first

Staying current

Each run checks for a newer gateway and installs it before starting, so npx -y permaura start is always the current build. Binaries are verified against a signed release manifest before they are swapped in: a download that doesn't match is refused rather than run. Pin to what you have with --no-upgrade, or update deliberately with npx -y permaura upgrade.

Where it puts things

Binary	~/.permaura/bin/permaura
Store (SQLite, includes the sealed vault)	~/.permaura/gateway.db
Operator token, minted on first clean start	~/.permaura/operator.token

Platforms

npx -y permaura start runs on macOS, Linux and Windows, on Intel and Apple silicon alike: it resolves and fetches the right binary for your machine.

What you get

Once it is running you have a live gateway on 127.0.0.1:7376. From there you can:

• add connections (including SSH) from the console or with permaura,
• point an MCP client at http://127.0.0.1:7376/mcp,
• drive it from the command line with the permaura CLI.

The gateway is a single self-contained binary and holds your keys locally; the npm package is just the most convenient way to fetch and launch it.