Start

Install and platforms

Fenzi is one command, fenzi. It runs on Apple Silicon Macs and Linux, and on Windows through WSL 2, which upstream marks experimental. The sandbox itself needs a container runtime or a VM, and a Linux kernel that can enforce filesystem rules.

Install the CLI

To read the script before it runs, download it, open it, then run it. It is short, and the same file is in the open-source repository.

This installs the latest release. It checks the download's sha256 and puts fenzi in /usr/local/bin when it can write there, or in ~/.local/bin. If that folder is not on your PATH, it adds one line to the profile of your shell: ~/.zshrc for zsh, ~/.bash_profile for bash on a Mac or ~/.bashrc on Linux, or ~/.config/fish/conf.d/fenzi.fish. The line ends with # added by the fenzi installer, is written once, and says which file it went to. Open a new terminal after that. That line is the only change the installer makes without asking; FENZI_NO_MODIFY_PATH=1 stops it. Then it starts fenzi setup, which asks before it installs or changes anything. It does not change your editor or your agent's settings.

Put them before sh, as in curl -fsSL https://fenzi.dev/install.sh | FENZI_NO_SETUP=1 sh. Check what you got:

  ■ Version

  ✓ Fenzi         <version>

That is this Fenzi release. The runtime release line it was built against is what fenzi doctor checks. See Versions and upgrades. To install on many machines at once, see Rolling out to many machines.

The sandbox runtime

The sandbox is OpenShell, an open source runtime. Fenzi drives it and does not replace any part of it. fenzi setup offers to install the pinned release, 0.1.2, with the upstream installer, and shows the command first. On a Mac that installer needs Homebrew, which also keeps the gateway running. Without Homebrew, setup says so and offers Homebrew's official installer first, showing its command; it asks for your password. On Linux the installer runs the gateway as a systemd user service, and setup restarts it there. To install it yourself, use the upstream packages for that release, then check the machine:

doctor checks the runtime version, the gateway connection, the sandbox driver, the image builder, the policy prover, and the settings that would weaken a sandbox. With --fix it removes those settings. It changes nothing else, and only after it says what it will change. It does not configure colima. When the gateway is down because Docker Desktop, colima, or another container runtime is stopped, doctor names it and fenzi setup starts it; see Container runtimes. Each failure and what to do about it is in Troubleshooting.

Platforms

Intel Macs are not on the list: the Mac app opens on one, but the sandbox does not run there. Native Windows enforcement is not on the list. No special hardware is needed anywhere.

Kernel requirement

Filesystem rules are enforced with Landlock, which needs ABI version 3 or later. Fenzi sets the policy so that a sandbox does not start without it. The upstream default would start the sandbox anyway and log a warning; we prefer a clear failure to a quiet hole.

On a Mac, this is about the Linux VM's kernel, not macOS. If a runtime's kernel cannot enforce the rules, the sandbox does not start, and fenzi run stops before the agent does.

Image builder

Each agent runs from an image built on your machine. Fenzi uses Docker if it is installed, then Podman. It needs one of them even when sandboxes run on the MicroVM driver. See Agent images.

Notes for Macs

• Docker Desktop is the path the upstream instructions describe.
• colima works once the gateway has three settings: the Docker driver, colima's socket, and host.docker.internal as the address sandboxes use to reach it, because they run inside colima's VM. fenzi setup writes them when you have no gateway config yet. See Troubleshooting.
• The MicroVM driver runs each sandbox in its own lightweight VM through Hypervisor.framework. It looks for the agent image in your local Docker or Podman before it pulls one.

What the install writes

The binary, and two folders the first time you run it: ~/.config/fenzi for state and a team sign-in, and ~/.cache/fenzi for compiled policies, saved logs, and staged changes. Model keys are not in either. They live in the runtime's own credential store. The full list is in the CLI reference.

Remove it

Stop any running sandboxes with fenzi stop, remove stored keys with fenzi key remove <agent>, then delete the binary and the two folders above. Your repositories are not touched; Fenzi never writes to them except through fenzi apply.

The Mac app

The app is where a developer works with the rest of the team without a terminal. It shows this machine's sandboxes, requests, approvals and decision log. On a machine signed in to a team it also shows the account and team, forwards decisions to the console, and sends a request to the console with Approve and add to policy, where an admin publishes it for every machine. Approve on its own answers on this machine, which the console shows as drift. Every screen runs a fenzi command and shows the line it ran, so install the CLI above first.

The app runs on macOS 14 or later, on Apple Silicon and Intel. The sandbox does not run on an Intel Mac, so there the app cannot start an agent. See Platforms.

Download Fenzi 0.2.2 for Mac

25d27d61a9a9bf9870c00d639ec473471396f07332b24f83e06b9d25e4de18db

Open the disk image and drag Fenzi to Applications. To check the download first, compare the sum above with shasum -a 256 ~/Downloads/Fenzi-0.2.2-unsigned.dmg.