These pages describe PrivacyFence 7.0.2. Download it · What changed

Configuration reference¶

PrivacyFence reads these configuration files and variables:

• settings.yaml: your policy and the daemon's own settings. It carries no secrets. Most of it is edited from PrivacyFence Settings; this page lists every key, including the ones with no control there.
• org_bundle.json: on a desktop install, the signed bundle of app credentials for the services it connects (Desktop configuration bundle). It is org_config.json in 6.x.
• On an organization server, instead of a bundle: environment variables, org/admin_config.json (written by the Admin page) and signed connector configs (Organization server settings).

Where the files live on each platform is in Platform support. They are owned by PrivacyFence's service account on a packaged install, so editing one by hand needs administrator rights.

The command-line options of privacyfence-app are at the end of this page (Command-line options).

How settings.yaml is read¶

• First start. If settings.yaml does not exist, the daemon creates it from the packaged example (src/privacyfence/resources/settings.yaml.example). The Seeded column below is the value that example writes.
• Missing keys. A key that is absent (or commented out) takes the Code default. Where the two columns differ, a fresh install behaves as Seeded and an install whose file lacks the key behaves as Code default.
• When changes apply. A change made from Settings applies straight away. A hand edit to the file applies at the next daemon start.
• Validation. An invalid privacy-filter value, step-up scope or batch, or an unreadable file stops the daemon at start with a configuration error naming the key. Auto-accept rules it cannot read are dropped, never treated as a match.
• Organization mode. The server's own settings.yaml is install-wide: privacy, the other *_privacy groups, pii_detection, logging and web.approvals apply to everyone, and web.mcp.enabled must be true. Each person also gets a settings.yaml of their own, of which only the auto_accept section is used. Keys marked local mode only have no effect on an organization server.

Exporting and importing personal settings¶

Settings > Auto-accept > Export… writes privacyfence-personal-settings.json (UTF-8 JSON, at most 256 KiB and 500 rules to import); Import… reads one back. It works in both modes and in every direction. Only the person's own auto_accept rules and step-up level move.

Import previews before it changes anything and gives each rule a status:

Import never removes or narrows anything. See Moving a person from a desktop install.

Earlier policy sections¶

A settings.yaml that contains an auto_accept_rules or auto_accept_grants section (even an empty one) is refused at start with a configuration error naming the section. Rules in those sections are not converted: remove the section and recreate the rules on the Auto-accept page.

If the same file also carries the top-level marker migrated_to_policy_v2: true, its rules are already in the auto_accept section. The daemon then removes auto_accept_rules, auto_accept_grants and the marker, rewrites the file, logs a warning naming what it removed, and starts. If the rewrite fails, it starts anyway and tries again next time. See ADR 0041 and ADR 0047.

settings.yaml keys¶

Privacy filter¶

Six groups, one per kind of data, each with a default_policy and per-category values. Each value is allow (pass unchanged), redact (replace with a placeholder that gives only the length; for a list-shaped category, same as block) or block (replace with [BLOCKED BY PRIVACY FILTER]). The filter applies before you see the data on a card, and it is a minimum: approvals still apply. Edited from Settings > Privacy Filter. Details: Approvals and policy.

Code defaults: a category that is not listed takes its group's default_policy. A group that is missing altogether is allow for everything in local mode and block for everything on an organization server.

file_metadata and file_list overlap (both can show a file's name and owners). If one is allow and the other is not, the daemon logs a warning at start.

Connector behaviour¶

PII detection¶

The PII check scans content shown on a card for likely personal data (bank account numbers, card numbers, national ID and tax numbers and similar, in English, German and Hungarian; email addresses and phone numbers are not detected) and asks for a second confirmation when it finds some. See PII detection keywords and Approvals and policy.

Auto-accept rules¶

The auto_accept section holds the rules that let a gated call run without a card. It is written by the Always allow button, Settings > Auto-accept and privacyfence_propose_policy_change, which all validate the rule and compute its id; prefer them to hand-editing. The scopes, verbs and conditions a rule can use are in Approvals and policy.

The seeded rule auto-accepts contact edits that change no email address or phone number. A missing or empty auto_accept section means nothing auto-accepts.

Logging and updates¶

Web server and MCP (local mode only unless noted)¶

Local file transfers¶

Passkey step-up (local mode)¶

Step-up asks for a fresh passkey (Face ID, Touch ID, Windows Hello) before an approving decision is released, and before a sensitive settings change (rules, grants, privacy policy, PII settings). Denying never needs one. Passkeys are enrolled at /security, linked from Settings > General > Security > Manage passkeys. An organization server reads the step_up section of org/admin_config.json instead (set on Admin → Step-up, below). Details: Approvals and policy and Security and compliance.

"Packaged install" means the macOS .pkg, the Windows installer or the .deb, which are privilege-separated. A source checkout or a pip/pipx install defaults both keys off. A value written in the file always wins over these defaults, in either direction.

The Turn on button. Once at least one passkey is enrolled, Settings > General > Security shows Step-up for approvals with a Turn on button. It writes step_up.enabled: true and step_up.require_passkey: true together and takes effect immediately, with no restart. There is no control to turn step-up off: set step_up.require_passkey (and step_up.enabled) to false in the file and restart. Changing scope or batch also needs a file edit and a restart. The button is not shown on an organization server.

Passkey required for. With step-up enabled, the same card shows the three scopes with the configured step_up.scope as the minimum; the ones below it are locked. Picking a wider one applies to your own approvals at once, with no restart, and is stored beside your passkeys (step_up_preference.json under the authority directory), not in this file. In organization mode every member sees this control, and the admin config's step_up.scope is the minimum. Once a passkey is required for settings changes, changing this needs one too. See ADR 0091.

AI system names¶

Desktop configuration bundle (org_bundle.json)¶

A desktop install reads one signed file with the app credentials for the services it connects. An administrator builds it with scripts/build_org_bundle.py (Python standard library only; --sign-key and --generate-signing-key also need the cryptography package), and people install it from Admin → Organization configuration (or it is placed in the org/ directory by hand). An organization server does not take a bundle: see Organization server settings. Pass only the options for the services you have registered: a connector is offered only if its section is in the bundle. Per-service registration steps are in Google Cloud setup, Slack setup, Salesforce setup, Atlassian setup, Grist setup and Miro setup; Telegram needs no registration (Telegram setup).

How the daemon treats the file:

• Absent: a desktop install has no organization credentials, and every connector that needs them is unavailable.
• Unreadable, not valid JSON, or not a JSON object: the daemon refuses to start.
• Signed: the first signed bundle an install reads pins its signing key; from then on every bundle, unsigned ones included, must verify against that key or the daemon refuses to start. To accept a new key, an administrator deletes the pinned org_bundle_signing_pubkey.txt in the organization config directory. Rotation after an upgrade is covered under Files in the org directory.
• File name: PrivacyFence 7 reads org_bundle.json. org_config.json is the 6.x name: on the first start after an upgrade the daemon copies it (and its two pin files) to the new names and leaves the originals untouched, and a later change to org_config.json is ignored with a warning.
• Operational settings in an older bundle (services offered, file delivery, step-up and the others listed under Refused options) are imported once into org/admin_config.json and afterwards ignored; every later start logs a warning naming them, and build_org_bundle.py --merge drops them.

Build options¶

Refused options¶

Every option that wrote an operational setting, and every option that described an organization server, is hidden from --help and refused with a message that says where the setting went; nothing is written. They are listed here because older runbooks and scripts still pass them.

Bundle keys not written by build_org_bundle.py¶

A bundle that still carries mcp.tool_annotations (only 5.0.0a1's build_org_bundle.py wrote it) stops the daemon from starting, with a message naming the key: PrivacyFence always tells AI clients truthfully which tools read and which write, and the option to say otherwise was removed. Rebuild the bundle; --merge drops the key. See ADR 0089.

Organization server settings¶

An organization server (Docker image or the systemd install) reads no bundle. It takes its settings from four places, and nothing else:

The reasoning is in ADR 0256, ADR 0257, ADR 0264 and ADR 0269.

Environment variables¶

An unset variable and one set to an empty value are the same. Several variables are comma-separated lists; spaces around each item are ignored.

Precedence. A legacy bundle's idp section wins over PRIVACYFENCE_IDP_* and PRIVACYFENCE_ADMIN_EMAILS, and the start logs that the variables are ignored. The same holds for a bundle's mode and server values. Without a bundle the environment is the only source. See Legacy bundle for moving off it.

A server stays a server. The first start with an identity provider records org_server in org/admin_config.json. After that, removing the identity provider variables is refused as a single-user start instead of exposing the server on its address with a setup code.

Admin config (org/admin_config.json)¶

Written by the daemon when an administrator saves a change on the Admin page; a desktop install keeps one too. It holds everything operational and is part of the backup. Do not edit it while the daemon runs, and do not rely on a hand edit surviving an Admin page save unless you restart afterwards. The only reason to edit it by hand is to relax a setting the page only lets you tighten (step-up), or to set a key the page has no control for. Stop the daemon, edit, start. A file that is not valid JSON, is not an object, or has an unknown version refuses the start.

Changes to services and the Salesforce login URL take effect at once. Every other section is saved and applied at the next restart; the page lists what waits. Privacy Filter and PII Detection changes on the page apply to the next request.

Connector configs¶

An organization's own OAuth app for Google, Slack, Salesforce, Atlassian, Miro or Grist is a signed text file, one per provider, stored unchanged at org/connector_configs/<provider>.txt (mode 0600) and verified against the pinned key at every start. A file that no longer verifies refuses the start and names the provider.

privacyfence-connector-config v1
provider: slack
serial: 2026110201
client_id: 1234.5678
client_secret: ...
signed_at: 2026-11-02T10:00:00Z
key: <base64 Ed25519 public key>
signature: <base64 Ed25519 signature over every line before "signature:">

• Fields come in exactly this order. Salesforce adds an optional login_url before signed_at (and calls the client ID and secret consumer_key and consumer_secret in its own section); Grist adds auth_server_url and server_url there.
• A value is printable ASCII, at most 512 characters; a file is at most 8 KB.
• Sign it with scripts/sign_connector_config.py (keygen, then sign) or the browser tool at https://privacyfence.eu/tools/connector-config/. Both produce the same bytes for the same input. The steps are in the organization guide.
• The first upload pins its key in org/connector_config_signing_pubkey.txt, after the administrator confirms the key's fingerprint on the page. A different key is refused. To rotate the key, stop the daemon and delete that file; the next upload pins the new one.
• Each provider's serial must be higher than any accepted before for that provider. The highest accepted serials are kept in org/connector_config_serials.json, which survives removal, so an older file cannot be put back.
• An upgraded server's app credentials are imported once from its legacy bundle as org/connector_configs/<provider>.json (not re-signed: the bundle's signature covered them), and a later upload replaces them.

Legacy bundle (org/org_bundle.json)¶

A server upgraded from 6.x has org/org_bundle.json, copied once from org/org_config.json. The daemon reads it only for mode, server and idp, and every start logs that. Its app credentials were imported as connector configs on the first start, and its operational settings into org/admin_config.json; the Admin page shows a notice while the file is present. A server installs no new bundle: an org_bundle.json that differs from the one adopted is refused at start.

To leave it, move the three settings to the environment and retire the file:

privacyfence-app --print-env-from-bundle --idp-secret-file ./idp_client_secret
# copy the printed PRIVACYFENCE_* lines to privacyfence.env, restart, then:
privacyfence-app --retire-bundle

--print-env-from-bundle never prints the identity provider's client secret: with --idp-secret-file PATH it writes the secret to a new file (mode 0600, never overwriting) and prints PRIVACYFENCE_IDP_CLIENT_SECRET_FILE=PATH. --retire-bundle checks that the environment yields the same mode, server address and identity provider, imports the credentials if that has not happened, records the retirement in org/org_bundle_adopted.json and deletes org_bundle.json. Going back to 6.x still works afterwards, because 6.x reads the untouched org_config.json.

Files in the org directory¶

org/ is under the data directory (~/.privacyfence/org/ of the account the daemon runs as). All files are mode 0600.

Command-line options¶

privacyfence-app is the daemon's executable. On a packaged install the service starts it; the options below are for running it by hand.

The sign-in options are for an install that is not privilege-separated (a source checkout or a pip/pipx install). On a packaged install the daemon refuses to run as your account, so they fail; connect services from Settings > Connectors instead (see Connecting a service). They need the app's credentials first (a desktop bundle, or on an organization server a connector config or the built-in app), except --telegram-setup and --peek-login (the latter asks for the Peek server address when none is configured).

privacyfence-companion¶

The companion app's own command. The packaged installs start it for you. --action, --serve and --launch are mutually exclusive.