Installation

macOS
Linux

brew install --cask wardplaneio/tap/wardcell

Or download Wardcell.pkg from the releases page and double-click it. Either way you are installing the same signed, notarized installer, and it does two things: puts Wardcell.app in /Applications, and puts wardcell on your PATH.

It asks for an administrator password — that is what the second half needs, since /usr/local/bin is root-owned.

Approve the extension, once

open /Applications/Wardcell.app

This opens System Settings → General → Login Items & Extensions and asks for admin credentials again. It is asked once per Mac; later versions replace the extension without prompting.

wardcell works before you do this. Skip it and every run takes the fallback: a real sandbox with the same policy, reaching the network through the proxy environment variables instead of transparently. Approving the extension turns transparent capture on, and from then on it is the default with nothing set.

Apple Silicon and macOS 13 (Ventura) or later. The installer refuses both otherwise rather than leaving something that cannot run.

Building it yourself needs a paid Apple Developer account — macos/docs/signing-setup.md, then make -C macos release.

Download the package for your architecture from the latest release and install it:

sudo apt install ./wardcell_<version>_amd64.deb      # Debian, Ubuntu
sudo dnf install ./wardcell-<version>-1.x86_64.rpm   # RHEL, Fedora, Alma, Rocky

arm64 / aarch64 packages are published alongside the amd64 ones.

The package pulls in bubblewrap, iptables, iproute2, util-linux and libseccomp. It installs the policy root at /etc/wardcell, owned by root, and on Debian and Ubuntu it installs and loads an AppArmor profile — see below for why that is needed.

Built against glibc 2.28, so it runs on RHEL 8+, Debian 11+ and Ubuntu 20.04+.

On Ubuntu 23.10 and later, wardcell also needs an AppArmor profile. Those releases refuse an unprivileged user namespace to any process that does not have one, and wardcell builds every sandbox inside a user namespace — so without it, no sandbox starts. The .deb installs it and loads it wherever AppArmor 4 is present, which is every release that imposes the restriction; if you installed some other way, it is a four-line file and the recipe is in Linux (Bubblewrap).

Everywhere else, user namespaces just need to be available:

sysctl user.max_user_namespaces           # want > 0

Verify

wardcell --version
wardcell policy verify

policy verify parses and merges the installed policy root without running anything. A clean result means your policy is valid.

Path
`/Applications/Wardcell.app`	the whole of wardcell: CLI, host, system extension
`…/Contents/Helpers/wardcell`	the CLI, symlinked to `/usr/local/bin/wardcell`
`…/Contents/MacOS/Wardcell`	the host — activates the extension, and `--status` reports on it
`…/Contents/Resources/policies`	the bundled policy tree, sealed by the bundle’s signature
`…/Contents/Resources/config.toml`	the default machine configuration
`/etc/wardcell/config.toml`	machine configuration, written only if absent, owned by root
`/etc/wardcell/policies/`	the default policy root, copied from the bundle: `base.sbx` plus the bundled fragment tree, owned by root
`.wardcell.sbx`	not installed — your optional workspace policy, written per directory

The CLI and the host are in different directories on purpose. They are wardcell and Wardcell, and the macOS boot volume is case-insensitive, so one directory cannot hold both.

Path
`/usr/bin/wardcell`	the binary. Links glibc and `libseccomp` dynamically, and calls out to `bwrap`, `unshare`, `ip` and `iptables` — the package depends on all of them
`/etc/wardcell/config.toml`	settings for wardcell itself, owned by root. Written on first install and never replaced, so your edits survive upgrades
`/etc/wardcell/policies/`	the default policy root: `base.sbx` plus the bundled fragment tree, owned by root
`/etc/apparmor.d/wardcell`	Debian and Ubuntu only: the profile that lets wardcell open a user namespace
`/usr/share/wardcell/`	what the package ships, which the postinstall copies into `/etc/wardcell`. Not the policy root — editing it changes nothing
`.wardcell.sbx`	not installed — your optional workspace policy, written per directory

The policy root is in /etc and owned by root because it is the security boundary, not ordinary configuration — see why /etc/wardcell. An upgrade replaces the fragments wardcell ships and removes any it no longer ships; your own fragments are left alone, as is zones.toml beside config.toml in /etc/wardcell. If your organisation manages the policy root itself, set policy_root.install_bundled = false in /etc/wardcell/config.toml and upgrades leave it untouched.

Point at a different root with --policy-root or $WARDCELL_POLICY_ROOT.

From source

git clone https://github.com/wardplaneio/wardcell && cd wardcell
cargo build --release -p wardcell-cli
./target/release/wardcell policy explain --policy-root ./policies --profile developer

Uninstall

macOS
Linux

brew uninstall --cask wardcell

Or, for a .pkg install:

# Remove the system extension first — deleting the bundle does not, and
# an extension whose app is gone keeps running with nothing to manage it.
/Applications/Wardcell.app/Contents/MacOS/Wardcell --deactivate

sudo rm -f /usr/local/bin/wardcell
sudo rm -rf /Applications/Wardcell.app
sudo pkgutil --forget com.wardplane.wardcell

The extension is only fully removed on the next reboot. Upgrading, in contrast, is just installing a newer .pkg over the old one — nothing to deactivate first, and a reboot only when the release changed the extension itself, which is rare. The macOS reference covers both, including how to tell and the token/reboot rules.

sudo apt remove wardcell

Neither removes /etc/wardcell/policies/. Delete it by hand if you want the policy gone too:

sudo rm -rf /etc/wardcell

Run logs live under your home and are left alone either way — on macOS at ~/Library/Logs/wardcell. Delete that directory too for a clean sweep.

Workspace policies stay where they are: each .wardcell.sbx belongs to the directory it is in, and is yours to keep or delete with that directory.