Citadel for Linux

An outbound firewall for any Linux desktop (GNOME, KDE, Hyprland, Sway, …), and in progress for macOS (macos/: watch-only today). Every app that tries to reach somewhere new waits at the gate, in the Citadel window or as a desktop notification with Allow once / Always allow / Block. Your verdicts become per-app policies; with citadel-helper they are enforced with nftables, and chosen apps can be routed through HTTP, HTTPS or SOCKS5 proxies.

This is the standalone edition of the Citadel Omarchy plugin: the same core, as a background service with its own window and tray icon.

Key features

• Ask at the gate. When an app connects somewhere new, Citadel asks. Answer in the window or straight from the notification: Allow once, Always allow or Block. A burst from one app is one notification. Unanswered requests fall back to your default after a timeout.

• Real host names. Connections are named after the names apps look up (api.example.com, not a CDN address), so a policy keeps working when the service moves to another address.

• Survives updates. Apps that install each version in its own folder (mise, asdf, nvm, Nix) keep their policies after an update, once you confirm.

• Per-app policies. A policy can cover:

  • an app
  • a host (subdomains included), an IP or CIDR, a port
  • an app only when a given script or program starts it
  • a zone

  The most specific policy wins. Search and filter them, and export or import them.

• Real blocking, per app. With citadel-helper, policies are enforced with nftables per app (its cgroup), not just per address. Blocking something also closes its open connections.

• Guarded, Open and Lockdown modes, with optional timers.

• Knows who started it. curl via backup.sh or git in ghostty, with the command line shown and its secrets (tokens, passwords, auth headers) masked. Short-lived connections are caught too.

• Integrity checks. Programs are checked against their package's checksums (pacman, dpkg or rpm). An allowed app that changes without an update comes back to the gate.

• Per-app proxy routing, like Proxifier.

  • Send chosen apps through HTTP, HTTPS or SOCKS5 proxies; logins are kept in your keyring.
  • It fails closed: if the proxy is down, the app is blocked, never sent direct.

• Threat feeds and imports.

  • One-click feeds: FireHOL, Spamhaus DROP, StevenBlack, HaGeZi.
  • Import AdGuard rules, Pi-hole lists, hosts files or any list URL.

• Explain. See who owns a destination (e.g. Google LLC). On request, your own AI agent (claude, codex, gemini, pi, …) explains what it's for and suggests allow or block.

• Traffic and history.

  • Live connections per app, with rates, countries and why each one is allowed or blocked.
  • 30 days of history: top apps, hosts and countries, and the decision log.

• Zones. Link Wi-Fi or wired networks to zones, and Citadel switches policies as you move.

• Runs quietly in the background. A user service that keeps working with the window closed, plus a tray icon and a citadel CLI. It works on GNOME, KDE, Hyprland, Sway and others.

• Shares policies with the Omarchy plugin, and steps aside while the plugin runs.

• Local and private.

  • No account, no telemetry.
  • Feeds and databases download only when you turn them on.
  • Explain sends nothing until you press it.
  • The only part that runs as root is a small helper that validates everything it receives.

On macOS, watching and the gate work from a checkout today. Blocking and proxy routing are built and wait for signing; see macos/.

Every feature in detail, and its limits: FEATURES.md.

How it fits together

Install

1. Dependencies

Optional:

Also needed, and present on every mainstream distro: systemd, cgroup v2, and a notification server (GNOME, KDE, mako, dunst, swaync… any freedesktop one). Integrity checks use the system's package database: pacman, dpkg or rpm.

The packages below pull in the required dependencies themselves.

2. Citadel

Arch Linux:

cd linux/packaging/arch && makepkg -si
systemctl --user enable --now citadel

Or run it from the checkout without installing:

bin/citadel-daemon &
bin/citadel-app

Debian 13 / Ubuntu, Fedora: build the package in a container, linux/packaging/build-in-docker.sh deb or linux/packaging/build-in-docker.sh rpm, then install the file from linux/packaging/out/.

Flatpak (window only): linux/packaging/flatpak/io.github.neatouk.Citadel.yml. The daemon and helper must still be installed natively; a sandbox can't see other apps' connections or change the firewall.

Then install citadel-helper (1.3 or newer) and switch Settings → Enforcement on to actually block.

Using the Omarchy plugin too? They are separate products that share the same policies (~/.local/share/citadel). Only one runs Citadel at a time: while the plugin is active, the service pauses by itself (no monitor, no firewall changes, no writes to your policies) and the window says so. To switch to the app, omarchy plugin disable neat.citadel; the service takes over within seconds, with the same policies. To switch back, enable the plugin again and the service steps aside.

Import from AdGuard, Pi-hole and hosts files

Policies → Import ▸ takes:

• AdGuard / AdGuard Home rules
• Pi-hole allow and deny lists
• hosts files
• plain domain lists
• Citadel's own export

Paste them, or fetch them from a URL (GitHub page links work).

Up to 200 blocked domains become policies you can see and edit. Bigger lists, like HaGeZi or OISD, become a feed. Fetched from a URL, the feed refreshes daily.

Regex rules and AdGuard options such as $client= or $dnsrewrite have no Citadel equivalent. They're skipped, and the import tells you how many.

Not a DNS ad blocker. Citadel blocks connections per app, so a listed domain is caught when Citadel knows the connection's host name, from its own name lookups or the app's request. Pi-hole and AdGuard Home block the DNS lookup itself. They work well together.

Development

make test                                  # model parity, daemon, integrity, QML (PySide6)
bin/citadel-daemon -v                      # run the daemon from the checkout
python3 app/citadel_app.py                 # run the window (needs PySide6)
# beside the Omarchy plugin: own folders, enforcement off
CITADEL_ALLOW_BESIDE_PLUGIN=1 CITADEL_STATE_DIR=~/.local/share/citadel-dev \
  CITADEL_RUNTIME_DIR=$XDG_RUNTIME_DIR/citadel-dev bin/citadel-daemon

• citadel/model.py is a port of the plugin's Model.js; tests/test_parity.py runs thousands of generated cases through both and requires identical results.
• tests/test_daemon.py drives the real socket API with a fake monitor and a fake helper; nothing privileged runs.
• tests/test_qml.py loads every tab offscreen and fails on any QML warning.

Layout

License

MIT, see LICENSE.