These pages describe PrivacyFence 7.0.2. Download it · What changed

Install on Linux¶

Desktop mode is deprecated. PrivacyFence's desktop install, the one this page sets up, is deprecated in PrivacyFence 7 and will be removed in PrivacyFence 8. Its built-in sign-in works only in organization mode and the Docker image. See Moving to organization mode for the two ways forward and for what to check before a later upgrade to 8.x: start 7.x once and look for "Ready for PrivacyFence 8" on the Admin page.

Start with Getting started if you haven't: it covers what you need and what happens after the install. This page covers the .deb for Debian and Ubuntu desktops; for other distributions and for arm64, see Other Linux systems and arm64.

Requirements¶

Ubuntu 24.04 or Debian 13 or newer (glibc 2.38 and systemd 242), on amd64 (Platform support). apt refuses the package on anything older, and there is no arm64 .deb.
sudo.
zenity or kdialog for the companion's dialogs. Ubuntu and Debian desktops ship one; see Platform support.
Claude Code or another Streamable HTTP MCP client. Claude Desktop has no Linux build, so there is no .mcpb step on Linux.

Download and verify¶

Download privacyfence_<version>_amd64.deb from privacyfence.eu/download. The page lists each file's SHA-256; compare it before installing:

sha256sum ~/Downloads/privacyfence_<version>_amd64.deb

Install¶

Install the package with sudo, from your own account:

sudo apt install ./privacyfence_<version>_amd64.deb

The package puts the self-contained application in /opt/privacyfence (it needs no Python packages from the system) and sets up privilege separation while it installs: it creates the privacyfence system account, keeps the data in /var/lib/privacyfence, runs the daemon as the privacyfence-daemon system service, and adds you (the sudo user) to the privacyfence group. Nothing is stored under ~/.privacyfence. If this setup fails, the package install fails. 2. Log out and back in. Group membership is only picked up at login; until then neither the companion nor your AI client can reach the daemon.

At each desktop login, an autostart entry starts the companion (privacyfence-companion --serve) in your session. It is what opens connector sign-in pages in your browser. The daemon itself does not autostart with your session: systemd runs it at boot, whether or not anyone is logged in.

Installing over an existing install: install the new .deb the same way. The package stops the service, replaces the program files and starts it again. Your data is kept.

Installed without sudo (as root, or by unattended-upgrades or a management tool), the package cannot tell who it is for; see Unattended .deb installs.

First start¶

Linux has no tray icon. The PrivacyFence entry in your Applications menu is the companion:

Clicking it opens Approvals; you are asked to confirm first (ADR 0031).
Right-clicking it (or your desktop's equivalent) offers Settings, Copy AI client token, New PrivacyFence recovery code, PrivacyFence service status, Start PrivacyFence, Restart PrivacyFence, Stop PrivacyFence and Quit PrivacyFence.

From a terminal, privacyfence-companion --action=open-settings opens Settings. After you log back in, the companion opens the Passkeys page until you have added a passkey; follow the first approval from there. Most Linux desktops have no passkey authenticator built in, so use what your browser offers instead: a USB or NFC security key with a PIN, or your phone, by scanning the QR code the browser shows. Any of them works, as long as it asks for your PIN, fingerprint or face.

Connect Claude Code¶

Claude Code talks to the daemon's local /mcp endpoint with your own bearer token. On Linux the URL is in /var/lib/privacyfence/handoff/mcp_url and the token comes from privacyfence-app --print-mcp-token, run from your own account after logging back in. The full command is in Connect Claude Code. Claude Desktop does not run on Linux, so the .deb carries no extension.

Troubleshooting¶

What you see	What to do
`--print-mcp-token` or the companion cannot reach the daemon	Log out and back in, then run `status` (below).
The daemon is stopped	Applications menu → PrivacyFence → Start PrivacyFence (asks for your password), or `sudo systemctl start privacyfence-daemon`. The companion also shows a desktop notification when the daemon has been down for more than 15 seconds.
The service keeps failing	`journalctl -u privacyfence-daemon -e` shows why.
A connector sign-in never opens a browser page	The `--serve` companion is not running in your session. Log out and back in, or run `privacyfence-companion --serve &`.
A first passkey enrollment is refused, naming `zenity`/`kdialog`	`sudo apt install zenity`.
Adding a passkey fails with "no built-in passkey authenticator ready to use"	The browser's prompt was closed before a security key or phone was used. Try again, and pick a security key or your phone in it.
You cannot use the Applications-menu entry	`privacyfence-app --print-sign-in-link` prints a one-time link; the companion asks you to confirm it before it can approve anything.

Check the whole install with status, and repair it with enable:

sudo privacyfence-privilege-separation status
sudo privacyfence-privilege-separation enable

Logs, data locations and start/stop commands are in Platform support. Problems common to all platforms are in Getting started.

Uninstall¶

sudo apt remove privacyfence

This runs privacyfence-privilege-separation uninstall: it stops and removes the service and the program files and keeps your data in /var/lib/privacyfence, together with the privacyfence account. Installing again picks it all back up (ADR 0042).

Purge (delete your data)¶

sudo apt purge privacyfence

This also deletes /var/lib/privacyfence (connector sign-ins, policy, passkeys, audit log) and the privacyfence account and group. It cannot be undone, and it works after a plain apt remove too.

Other Linux systems and arm64¶

There is no .deb for arm64 and no package for other distributions. On those systems you can install the Python package from PyPI (Python 3.11 or later):

pipx install privacyfence
privacyfence-app

PrivacyFence itself is pure Python, but only amd64 Linux is tested, so on arm64 you are on your own. Know what this install is before you rely on it:

It is not privilege-separated. The daemon runs as you, and so does your AI client, which can therefore read and change your policy and audit log. The data directory is ~/.privacyfence.
Passkey step-up is off by default, because a passkey store your AI client can write proves nothing. You can turn it on in settings.yaml (Configuration reference).
To start it at login, copy the repository's privacyfence.service to ~/.config/systemd/user/ and run systemctl --user enable --now privacyfence.

Connect Claude Code as above, reading mcp_url from ~/.privacyfence/mcp_url. Uninstall with pipx uninstall privacyfence; delete ~/.privacyfence to remove your data.