What Permaura protects
Permaura gives agents permission instead of keys. This page says exactly where that holds, because a security promise without a stated edge is worth less than a smaller one with a clear edge.
The short answer
| If you run Permaura… | The promise holds | Worth knowing |
|---|---|---|
| On your own server or VPS | Yes, as written | Anyone with root on that machine has everything on it |
| As a hosted worker | Yes, for the agent | A worker decrypts your secret to make the call, so our infrastructure is inside the trust boundary. Not zero-knowledge |
| With remote access on | Yes, as written | A leaked agent token then works from anywhere, not just your desk |
| On your laptop, alongside agents running as you | Only for what a device has to sign | The rest of this page |
If you are in the last row, read on. If you are not, the rest of this page is background.
What the gateway does for you
When an agent calls a capability, the gateway checks your policy, adds the real credential on its own side, runs the call, and returns a result with secrets stripped out.
The agent holds a token that says what it may do. It never receives the credential, cannot read it out of the response, and every call lands on the audit log. That is the part that does not change no matter where you run it.
Where it stops, and why
The gateway keeps three things in one folder, owned by whichever user account it runs as:
~/.permaura/
vault-kek the key that unlocks every credential you have stored
operator.token the token that authorizes any action on this gateway
gateway.db the encrypted store itself
Those files are readable only by that user account. On a server that is you and nobody else, and the story ends there.
On a laptop it is different, and the difference is the whole point of this page. An agent you run is running as you. Your operating system cannot tell your terminal apart from a coding agent, or from a script that came with a package you installed. As far as it is concerned they are all you, so they can all read those three files.
An agent that reads operator.token and presents it gets a valid session. Nothing was broken to do that. It asked using your credentials and got a correct answer.
Any tool that keeps a usable credential in your home folder works this way, whether it says so or not. We would rather write it down.
What stands in the way
A physical device has to approve the things that matter. These all wait for a paired device to sign them:
- Exporting your vault
- Deleting a stored credential
- Deleting a connection, and everything that depends on it
- Deleting an agent, a policy or a grant
On a Mac that is Touch ID, shown by macOS itself. A token someone copied cannot produce a fingerprint, which is the whole point: it is the one credential that is not a file.
If you have no device paired, these go ahead as normal, because a gateway you can be locked out of is worse than one you can empty. Pair more than one where you can: losing every paired device puts you into account recovery rather than a quick fix.
Your sign-in stays in the system keychain. The desktop app keeps your account tokens in the macOS Keychain or Windows Credential Manager, not in a file. A program that is not the app gets an approval prompt instead of your tokens.
The gateway keeps its own encryption key, in the Keychain on macOS and Credential Manager on Windows, tied to the signed app. On Linux it can take the key from a TPM-sealed systemd credential where you set one up.
Exactly what is exposed, and where
The three files above are not equally well protected, and the difference is not the same on every operating system. This is the honest version.
| What a program running as you can get | macOS | Windows | Linux | Linux with --service-user |
|---|---|---|---|---|
operator.token, and with it every action on the gateway | Yes | Yes | Yes | No |
| The vault key, straight out of the OS credential store | It has to ask you first | Yes, silently | Yes, once your keyring is unlocked | No |
| The encrypted store file | Yes | Yes | Yes | No |
| Any credential you have stored, in plaintext, by asking the API for it | Yes | Yes | Yes | No |
| Exporting your vault, deleting things, lowering the approval floor | Only with a signature from a paired device | Only with a signature from a paired device | Only with a signature from a paired device | Only with a signature from a paired device |
Read the last row first. It is the one that does not move, and on a laptop it is doing most of the work.
macOS protects the vault key best. Keychain access is recorded against the code identity of whatever asked for it, so a different program requesting the gateway's key gets a dialog rather than the key. It does not protect the operator token, because that is an ordinary file, and a token is enough on its own.
Windows is the weakest of the three, and there is currently nothing that closes it. Credential Manager is per-user with no equivalent of that code-identity check, so a program running as you reads the vault key without a prompt. It is still better than leaving the key in a file, and there is no --service-user on Windows. Pair a device.
Linux is the only one where you can move the boundary into the kernel. By default the key is in an owner-only file, or in your keyring on a desktop, and neither stops a program running as you. --service-user does.
Moving the line further out
On Linux you can give the gateway its own user account, which is the only option here that makes your operating system enforce the boundary rather than Permaura:
sudo sh -c "curl -fsSL https://permaura.com/install | sh -s -- --service-user"
Permaura then lives in /var/lib/permaura under its own permaura account. Nothing running as you can read the store, the key or the token. An agent on your machine ends up in the same position as one on the other side of the world: it can use the API with an agent token and do nothing else.
That is the boundary working, not a fault, but plan for it. You run the gateway from your Permaura account instead, the same way the phone app and the web console already do, or locally with sudo -u permaura. If you have neither an account nor sudo on that machine, you will be locked out of your own gateway. It is off by default for that reason.
It is Linux only on purpose. On macOS and Windows the gateway would have to give up the system keychain that protects its encryption key in order to gain a separate account, which is a swap rather than an improvement.
Account recovery is a trust choice
Turning remote access on makes your gateway an OAuth resource server for permaura.com, and that has a consequence worth stating plainly. A permaura.com recovery ticket becomes a third authority that can loosen trust on the gateway, alongside your paired device and your recovery codes.
It exists for a real case. If the device is lost and the codes went with it, that ticket is how you get back in rather than starting over with a vault you can no longer open.
The cost is that an account-recoverable gateway trusts the account, and the server that issues the ticket, as part of its custody. A compromised authorization server could assert the re-authentication itself. A gateway with no remote access configured has no such route and no such trust: the device and the codes are the only authorities, and if both are gone the vault stays sealed.
Neither answer is the right one for everybody, which is why it follows remote access rather than being a setting of its own. Turning remote access on is the moment you accept the ticket as an authority.
What to do
- Running on a server? Nothing. The promise holds as written.
- Running on your laptop with agents? Pair a device. It is the only control that works on all three operating systems, and it is what stands between an agent that read your token and an emptied vault.
- On Linux, and want the boundary the kernel enforces? Use
--service-user, and read the warning above first. - Turned remote access on? Revoke an agent token you no longer trust. A token is a bearer: until you revoke it, whoever holds it is that agent.
- Turned remote access on? Know that a permaura.com recovery ticket can now loosen trust on this gateway. That is the trade for being able to recover an account when the device and the codes are both gone.
- On macOS? Let the desktop app install and supervise the gateway. That is what keeps the vault key under a Keychain entry tied to a signed binary rather than in a file.
- Anywhere: hand the vault key to the gateway in a file it reads at startup, never in an environment variable. Anything running as you can read a variable out of the process, every program the gateway starts inherits it, and clearing it later does not help, because the value a reader sees is the one the process started with. From gateway 1.3.5 the old
PERMAURA_VAULT_PASSPHRASEis ignored outright and the gateway says so on startup, so if you are still setting it, move the value toPERMAURA_VAULT_PASSPHRASE_FILEbefore you upgrade.