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
npx -y permaura start --pair PGW-XXXXXXXX
The pairing code comes from the console's "Connect a gateway" dialog. With --pair 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 --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) |
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_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 |
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
permauraCLI.
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.