Uninstall & reset

Permaura is easy to take out again, and worth knowing how to before you put it in. Work top-down: revoking access takes effect immediately, whereas deleting files does not revoke anything on its own.

Revoke before you delete

Deleting the gateway's files does not revoke anything by itself. A gateway that is still running keeps serving the database it already has open, any copy of gateway.db you restore later still trusts the agents and devices it held, and permaura.com keeps this machine's link to your workspace until something removes it. Do the console steps first, then remove the software.

Cut off access right now

If you need everything to stop this second, you don't have to uninstall anything.

• One integration: open the connection and hit its kill switch. Every call through it is refused instantly, across every agent and grant.
• Everything: stop the gateway. A gateway that isn't running can't act, whatever any grant says. (There's also a global pause on the gateway itself, reachable from the REST API as POST /v1/broker/pause, which halts every call without taking the process down.)
• One agent: remove it on the Agents page. Its sessions are revoked immediately, and grants that named only that agent are deleted with it, so it can't quietly return with access you thought you'd taken away.

Stop the gateway

Running from the terminal

Ctrl-C in the window it's running in. To find and stop one you've lost track of:

pkill -f permaura

Running under the desktop app

Quit the app. It supervises the gateway and stops it on the way out.

Remove the gateway and its data

Everything the gateway installs and stores lives in one directory: ~/.permaura (or wherever you pointed PERMAURA_HOME). Inside it are bin/permaura and gateway.db. Outside it are the PATH link and the boot service covered below, and, on macOS and Windows, the key that unlocks the vault, which the gateway keeps in the Keychain or Credential Manager. On Linux the gateway never uses a desktop keyring: the key is an owner-only vault-kek file inside the gateway's home, so deleting the home deletes the key with it, unless a root install sealed it to the TPM. That install keeps it as a root-owned systemd credential, vault-kek.cred; where the gateway runs as its own service user (permaura by default) the file is /etc/permaura/vault-kek.cred, outside its home in /var/lib/permaura. From gateway 1.3.42, sudo permaura uninstall --purge-data run against that service install removes it with the data (permaura vault forget-key removes a sealed copy kept in the gateway's own home). On an older gateway, or after removing the directory by hand, delete it as root:

sudo rm /etc/permaura/vault-kek.cred

What goes with gateway.db, and what your account keeps

gateway.db is a self-run gateway's whole setup, and permaura.com holds no copy of it:

• your connections, their sealed credentials and their capabilities
• your policies and grants
• your agents and their sessions
• the devices it trusts to sign approvals, its recovery codes and its approval floor (the device list and the floor move to files of their own only if you set PERMAURA_APPROVER_KEYS_PATH)
• the local audit chain

Your account on permaura.com keeps your sign-in, your organizations, workspaces and members, your plan, and your phones' notification registrations. It also keeps this gateway's link to your workspace until permaura uninstall or the console removes it. It does not keep connections, policies, grants or audit history, so a fresh gateway paired to the same workspace starts empty.

Decide what to keep before you delete anything

• Keep the data for a reinstall. permaura uninstall revokes this machine's links from every permaura.com workspace, stops the gateway, removes the boot service, the PATH link and the binary, and leaves the data where it is. It lists those steps and asks before doing anything, and says:

  (data under /Users/you/.permaura stays; a reinstall resumes with it. Add --purge-data to delete it.)

  Reinstall later and the gateway comes back with everything it had; pair it again to reconnect it to your workspace.

• Export it to a file. While the gateway is still running:

  permaura vault export --out ~/permaura-vault.json

  It asks for a passphrase and writes one encrypted file, owner-only. If a device is paired and the approval floor is not lowered, the export waits until you confirm it there. Keep the file outside ~/.permaura, and the passphrase somewhere else: Permaura keeps no copy of either, so a lost passphrase is a lost bundle. The console does the same from Vault → Download my data, except on a gateway you run yourself with no device paired, which refuses an export from the console from gateway 1.3.44; use the command above there.

  On the next gateway, permaura vault import ~/permaura-vault.json (or Vault → Import a vault in the console) brings back your connections, their credentials and capabilities, your policies and your grants. It does not bring back agents (connect them again), sessions, trusted devices or recovery codes (pair a device again), the approval floor (set it again), connectors you installed yourself (install them again), or the audit chain. Install those connectors again before you import if you can: without the signed manifest that vouches for them, a connection's reads sent as POST (a search, a report, a GraphQL query) come back asking for an approval on every call, and the import's review lists them. From gateway 1.3.56, installing the signed manifest afterwards returns them to the posture it gives.

• Delete it. permaura uninstall --purge-data does everything the plain uninstall does, then forgets the vault key and deletes gateway.db, its schema backups, the gateway's tokens, the managed tunnel's credentials, configuration and any stop record (tunnel-credentials.json, cloudflared.yml and tunnel.stopped) and this machine's install identity. Or remove it by hand, as below.

Removing it by hand

This deletes your whole setup, not just your secrets

Once gateway.db is gone, so are your connections and their credentials, your policies, grants and agents, the devices the gateway trusts, and the local audit chain. Your account on permaura.com does not hold a copy of any of them. The only ways back are the data you kept or a bundle you exported first; without either, you pair a fresh gateway and set everything up again. If you might want the audit trail, read it out first: the console's Audit log page, or permaura audit.

On macOS and Windows, first forget the vault key. It lives in the Keychain or Credential Manager, outside the directory you are about to delete, where it would still open any copy of gateway.db kept elsewhere, and removing it needs the binary:

permaura vault forget-key --yes

Then take the permaura command off your PATH, while the binary is still there to do it:

permaura unlink

The installer and the desktop app put a symlink on your PATH pointing into ~/.permaura/bin. Like the boot service below, it lives outside the directory you are about to delete, so removing the directory first leaves a permaura on your PATH that points at nothing; unlink needs the binary in order to run, so afterwards it cannot clean up after itself. It only ever removes a link Permaura created, and says so when it leaves anything else alone.

Then remove the directory:

rm -rf ~/.permaura

That removes the binary, the local store, and the sealed vault it holds, and on Linux the vault key with them. It does not unlink this machine from your workspaces; permaura uninstall --purge-data does that as well as everything above, so prefer it while the binary is still there.

If you deleted the directory first

Nothing is broken, but a dead permaura is still on your PATH. Find and remove it by hand:

ls -l "$(command -v permaura)" && rm "$(command -v permaura)"

Check where it points before you delete it. If it resolves somewhere other than ~/.permaura/bin or Permaura.app, it belongs to something else.

If you installed it with the one-liner, remove the boot service too

permaura uninstall removes this for you; these are the commands if you are doing it by hand. The curl installer registers the gateway to start on its own: a systemd unit on Linux by default, and a login agent on macOS if you asked for one with --service. That registration lives outside ~/.permaura, so deleting the directory leaves it enabled and pointing at a binary that is gone.

# Linux, whichever of the two you have
sudo systemctl disable --now permaura && sudo rm /etc/systemd/system/permaura.service
systemctl --user disable --now permaura && rm ~/.config/systemd/user/permaura.service

# macOS, only if you installed a login agent
launchctl bootout gui/$(id -u)/com.permaura.gateway
rm ~/Library/LaunchAgents/com.permaura.gateway.plist

Remove the desktop app

If the app runs your gateway, use the gateway's Uninstall button in the app first: it offers the same choice to keep the data or delete it, and Export Data beside it writes the encrypted bundle. Then quit the app and drag Permaura from Applications to the Trash. Its own preferences live under ~/Library/Application Support/com.permaura.desktop; remove that too for a clean slate. Deleting the app does not delete ~/.permaura, so do both if you want the gateway gone as well.

Turn off remote access

Press Pause on the gateway's card under Settings → Gateway, which keeps the name reserved, or Modify and then the red delete button to remove remote access and give the name up, which keeps it held for your organization for 45 days and then lets anyone claim it (more); a bring-your-own address has only the delete. Either way the public URL stops answering. With the desktop app your gateway is relaunched local-only; running headless, run permaura remote disable on the gateway's machine and restart the gateway.

The public hostname is stable and reserved for you: turn remote access on again later and you get the same URL back, so anything already pointed at it keeps working.

Unpair an approval device

Open Workspace → Devices and revoke the device, or do the same from Manage → Devices in the app, on a hosted gateway or one you run yourself with remote access configured. Either one asks you to confirm it's you first, and then the device's signing key is no longer trusted on that gateway. On a hosted gateway a member can revoke only a device they paired themselves; anyone else's, or any device on a gateway you run yourself when done from the console or the app, takes an owner or admin. From gateway 1.3.46 that takes effect at once for the gateway's owner, for anyone holding Remove any approval device alone, and for a device recorded as your own; anyone else's removal of another person's device waits for a device of someone other than them to confirm it, and lapses after 24 hours, as Approvals describes.

Notifications are a separate registration, held by permaura.com rather than the gateway. To stop a phone being told about held actions, turn off Notifications under Settings → This phone in the app. Removing it under Workspace → Notifications lasts only until the app next opens on it, because the app registers the phone again at every launch while that switch is on. An owner or admin taking a device away from someone can use Remove from organization on that page, which also asks each gateway in the organization that Permaura can reach to revoke its signing key after one confirmation. It does not ask a gateway it cannot reach, one whose managed tunnel is stopped, one whose trusted keys it cannot read, or one where it cannot confirm the key is that phone's, and it names those as still owing the revocation, to be revoked at the gateway's machine when its managed tunnel is stopped, and otherwise on the gateway's Devices card or at its machine. A gateway that binds the key to another account is not asked either, and its line in the report says to revoke the key on its Devices card if it is that phone's. A gateway it asks holds that removal the same way unless you are its owner or hold Remove any approval device alone. The phone's notifications stay stopped only until its owner next opens Permaura on it, and removing that person from the organization is what stops them for good; Approvals covers when they stop and the Dismiss removal control.

On a gateway you run yourself, you can also revoke from the gateway's own machine, in the desktop app or with permaura approver revoke, and that asks nothing of permaura.com. With no remote access configured it is the only way: the console counts as a remote caller there, and the gateway refuses the removal. Wherever you start it, removing the last usable device on such a gateway waits until that device signs it or you enter one of the gateway's recovery codes, because it switches off every hold that needs a device signature.

Unpairing your last device does not lower the approval bar

Device-signed actions need a paired device, and if your gateway's approval floor is raised, so does every other approval. Revoking the last device does not lift either. That's deliberate: otherwise anyone holding your account session could clear the bar by removing a device.

Pair a replacement, or lower the floor. Where you can lower it from depends on the gateway: on a local or tunneled one, only from the machine running it; on a hosted one, from the console under Workspace → Devices after you confirm it's you, and while a working device is still trusted that device has to sign the change as well. See Approvals, and Playbooks for a hosted gateway whose last device is gone.

Revoking on hosted also un-blocks the next enrollment

On a hosted gateway, a second approval device is normally held until a device you already paired confirms it. Revoke every device first and that requirement drops, so a replacement enrolls on your confirmation alone. From gateway 1.3.46, revoking the last trusted device takes the gateway's owner, or an owner or admin of its organization who holds Remove any approval device alone or is removing their own device, since anyone else's removal of it waits for a confirmation only that device could give; on an older gateway any owner or admin of its organization can. Pairing a replacement while none is trusted takes the gateway's owner or an owner or admin of its organization. It's the recovery path, and it's the reason to revoke before you pair rather than after.

Doing the whole recovery means confirming it's you twice, once to revoke and once to pair, and neither proof can be spent as the other.

Reset a workspace without starting over

To hand a workspace a clean slate while keeping your account and plan:

1. Remove every agent (revokes their sessions).
2. Delete the grants, then the policies, then the connections, in that order, since each is referenced by the one before it.
3. Stop the gateway and delete ~/.permaura/gateway.db, then pair a fresh gateway.

Cancel a paid plan

Settings → Billing → Cancel. You keep the plan's features until the period you've already paid for ends, then drop to Free. Canceling leaves your local setup alone: the local loop (connections, policies, grants, audit) keeps working, and you lose the paid reach features. A hosted gateway is different: it is paused for a grace period, then kept for 96 hours so you can export its vault, and then deleted. A managed tunnel stops answering when the pause starts and is deleted at the same point, though its name stays reserved for the gateway. Paying again before that deletion picks up where you left off; Trials & billing has the timeline.

Close your account

Settings → Account → Delete account (/settings/account/delete), or Delete account in the iPhone app (on the App Store), which opens the same page. It takes two confirmations:

1. Enter your password on that page. Permaura emails you a confirmation link, good for 24 hours. Nothing has been deleted at this point.
2. Open the link and confirm once more. That's the point of no return.

The page tells you up front exactly what will go, so you're never sent into a flow that fails at the end:

• Organizations where you are the only owner are deleted with you, and their workspaces, gateways, connections and audit rows go with them. That holds even when other people are members: they lose access to it and keep their own accounts. To keep such an organization, make someone else an owner first.
• Organizations you're a member of, or one of several owners of, carry on. You lose your access; nobody else is affected.

What you have to resolve first

Deletion is blocked, with the reason shown on the page, until each is cleared:

• A live subscription. Cancel it first. Canceling someone's billing as a side effect of a deletion isn't ours to do quietly, and leaving it running would keep charging someone who believes they're gone. A plan you've already canceled but are still inside the paid period for does not block you.
• A hosted gateway. Remove it in the console first. Within a few minutes it refuses your agents (from gateway 1.3.51 that includes agents connected with a setup code), but its vault stays downloadable for 96 hours (unless you choose Delete now), and your account can be deleted once that window has closed and the gateway has been torn down.
• A checkout or a cancellation still settling. If a checkout or a subscription cancellation has not yet settled with the payment processor, deletion waits for it; try again later.
• A gateway you linked that other people still use. If it belongs to an organization that will outlive your account, deleting the account would take it away from everyone else there. Disconnect it first, or ask an owner of that organization to.

Paying for a seat never gives you the power to delete somebody else's account, so other members' accounts survive whatever you delete.

What you cannot undo

There is no restore through the console and no grace period after the second confirmation. Read out anything you want from the audit log before you start.

permaura.com never held a copy of a self-run gateway's credentials, so deleting your account leaves nothing of them with us. A hosted gateway is different. Permaura keeps encrypted daily copies of its store, sealed credentials included, and they outlive the teardown: the last of them ages out 31 to 38 days after it. The keys that open them are destroyed on a 45-day timer, so until that last copy is gone the gateway can still be restored. Its archived audit log is held under a 39-day retention lock that nobody can shorten, so the most recent part of it outlives the teardown as well.

Deleting your account doesn't touch the software on your machine. Stop and remove the gateway separately, as above.