Step 2 — Connect a gateway
The gateway is the program that holds your keys, enforces policy, and makes the actual calls. It's a single self-contained binary. Connecting one is what turns the demo console into your console.
As soon as you sign up, the welcome dialog offers three ways to get a gateway running:
| Choice | Best for | Where it runs |
|---|---|---|
| Let Permaura host it | The quickest start, always-on, nothing to install | Permaura's cloud (hosted) |
| Install the desktop app | A local gateway your computer supervises for you, on macOS, Windows or Linux | Your machine (local) |
| Use the command line | Power users, servers, headless boxes | Wherever you run the command |
Not ready? "I'll set this up later" drops you into the console, and "View the demo" fills it with sample data so you can look around first.
The same three options live on the Gateway settings page (Settings → Gateway), so you can start or change your gateway at any time:
The desktop app and the command line run the same gateway
Two of those choices put a gateway on your own machine, and it is worth being explicit that they are not two different products. There is one permaura-gateway binary. The desktop app does not contain a second, cut-down version of it — it ships that same binary and runs it for you, on the same 127.0.0.1:7376 and against the same local database as a gateway you start from the terminal. What you get for installing the app is a supervisor, not a different gateway:
- It starts the gateway and keeps it running — at login if you ask it to, and again after a crash or a reboot, so there is no terminal window you have to leave open.
- It updates the gateway for you, verifying each build against Permaura's signed release manifest before swapping it in.
- It adopts a gateway that is already running rather than starting a second one. If you installed from the terminal first and then install the app, the app takes over supervising the gateway you already have; your connections, grants and audit log are exactly where you left them.
- It approves things. The app is also an approval device — a held request can be released from the menu bar or system tray, confirmed with Touch ID on a Mac. See Approvals.
So the choice between the app and the command line is a choice about who keeps the gateway alive, not about which gateway you get. Install the app on a laptop you use; use the command line on a server, a headless box, or anywhere you would rather manage the process yourself. The app is available for macOS, Windows and Linux at permaura.com/download.
The macOS app is signed and notarised. The Windows and Linux builds are not yet, so Windows SmartScreen will warn you that the publisher is unknown — choose More info, then Run anyway. Signed builds are coming. Gateway updates are signature-verified either way.
Auto-pairing, in one sentence
However you install it, the signed-in console mints a one-time pairing code (short-lived, single-use). The installer redeems it as the gateway starts, which registers the gateway to your account. You never copy or paste a URL or a token — the console notices the new gateway and goes live on its own.
Run it from the command line
Choosing Use the command line shows a ready-to-run command with your pairing code already filled in. Pick whichever you prefer:
- npm (recommended)
- curl (no Node)
- npx (nothing installed)
npm
If you have Node, install it once and permaura is on your PATH for good:
npm i -g permaura
permaura start --pair PGW-TF9YZJWF4V
Every command after this is just permaura: permaura status, permaura stop, permaura grant .... It works the same on macOS, Linux and Windows.
Every run checks for a newer gateway and verifies it against Permaura's signed release manifest before installing it, so the gateway stays current on its own. The launcher is npm's, so refresh that occasionally with npm update -g permaura. See the gateway package for its flags and where it puts things.
curl
No Node on the machine, or you want the gateway to come back after a reboot. Copy the command and paste it into your terminal:
curl -fsSL https://permaura.com/install | sh -s -- --pair PGW-VUZFQ3BPMX
It downloads the gateway, starts it on 127.0.0.1:7376, and pairs it to your account. --pair <code> is filled in for you; the code above is an example, and yours is unique and lives for a few minutes.
Already using port 7376 for something else? Add --port:
curl -fsSL https://permaura.com/install | sh -s -- --pair PGW-VUZFQ3BPMX --port 8799
npx
For a one-off, or a machine you will not keep. Same outcome as the other two, with nothing left on your PATH afterwards:
npx -y permaura start --pair PGW-TF9YZJWF4V
The -y answers npm's one-time "install this package?" prompt for you, so nothing stalls waiting on a keypress. Note that npx resolves the package from wherever you run it, so a directory that happens to contain a package.json and a node_modules will make it slow.
The pairing code has a live countdown; if it lapses before you run the command, the dialog mints a fresh one automatically.
The gateway runs on macOS, Linux and Windows (Intel and Apple silicon alike). npm i -g permaura covers all three; the curl one-liner covers macOS and Linux. Prefer nothing installed at all? Choose Let Permaura host it.
A gateway on a cheap cloud VM is always on and reachable from anywhere, with no tunnel and no paid plan. It needs a couple of things this page does not cover, chiefly TLS in front of it, since the gateway cannot terminate TLS itself. Self-host on a cloud VM walks through the whole path.
npm and npx both check for a newer gateway on every run and install it. The curl one-liner pins a fixed release and never upgrades itself, which is what makes it reproducible, but it also means a gateway installed that way stays on whatever version was current the day you ran it.
Two consequences worth knowing:
- The pinned release the installer hands out can lag the latest gateway. Check with
curl -s http://127.0.0.1:7376/health | jq .versionagainst the npm package. - To update a
curl-installed gateway, runpermaura upgrade. It verifies the new binary against the signed release manifest, swaps it in, and restarts whatever is running the gateway, because replacing the file alone leaves the live process serving the old code. Use--no-restartto stage it for a maintenance window instead. Re-running the one-liner does the same and additionally rewrites a systemd unit or launchd agent written by an older installer, so reach for it after an install-time change rather than for a routine update.
If you would rather not think about it, use the npm tab: the gateway keeps itself current, and each binary is verified against Permaura's signed release manifest before it is swapped in. One thing npm does not update on its own is the launcher that does the checking, so run npm update -g permaura now and again.
Already have a gateway running?
If you started a gateway some other way and just want to point the console at a specific address, open Settings → Gateway and use the Advanced section to set the browser URL your console should read from (for example http://127.0.0.1:8799).
A gateway's bearer token is sealed with AES-256-GCM and stored apart from the gateway record. When the console needs to reach a remote gateway it goes through a server-side proxy that decrypts the token only to make the call — the browser never sees it.
The console waits, then connects itself
Whichever method you pick, the connect card polls — "Waiting for your gateway to connect…". The moment your gateway registers, it flips to a green "Gateway connected" and the page refreshes on its own. There's no button to press.
Nothing showing up? Troubleshooting covers expired codes, port clashes, and a gateway the console can't see.
➡️ Continue to Step 3 — Go live.