Reference

Versions and upgrades

Fenzi pins what it depends on: the sandbox runtime's release line, and the exact version of every agent. A pin moves only after we have read the upstream release notes and run the checks again.

The runtime pin

  ■ Version

  ✓ Fenzi         <version>

fenzi --version prints the same thing.

This Fenzi release is built against the OpenShell 0.1 release line and installs OpenShell 0.1.2: fenzi setup offers exactly that release. fenzi doctor reads the installed version and fails if it is outside 0.1, naming the version to install. Exit code 3 means the runtime is missing, outside the line, or not connected.

We pin because the runtime's flags and output can change between minor releases, and Fenzi reads that output. A pin is cheaper than a silent misread.

Agent versions

An agent's network rules name the real path of its program, and that path can move between versions. So each version is pinned in the agent's Dockerfile and checked against the catalog before a release. CI also rebuilds every image weekly and checks those paths again; see Why the real path matters. fenzi agents shows the versions your CLI pins.

Upgrade Fenzi

When a newer release is published, commands end with one line that says so: fenzi <new version> is available. You have <your version>. Run fenzi update.

1. Run fenzi update. It downloads the new CLI, checks its sha256 against the release's checksum list, and replaces the command in place. If the folder it lives in is not yours to write, run sudo fenzi update, or the install line again. fenzi update --check only says whether there is a newer release.

2. Run fenzi doctor. If the release moved the runtime pin, it names the version to install.

3. Rebuild agent images whose version changed: fenzi agents build <agent>. run builds a missing image on its own.

4. Start new sandboxes. Running ones keep the program they started with.

Policy files do not need to change. The schema is versioned with version: 1, and a new schema version would come with a migration note.

The update check

At most once a day, a command fetches https://fenzi.dev/dl/latest.txt in the background and remembers the answer in ~/.cache/fenzi/update.json. The request carries no account, machine id, project, or policy. Our web server sees the address it came from and writes it to its access log, as it does for every page. The download count itself is a number per file and day. The check gives up after three seconds. On the day it runs, a command waits at most a second and a half for the answer before it exits.

It only runs when a person is at a terminal. It is skipped when CI is set, for builds without a release number, and for update and version. Set FENZI_NO_UPDATE_CHECK=1 to turn it off.

How a pin moves

• Runtime. Read the upstream release notes and migration guide, re-record the outputs Fenzi parses, run the test suite against them, then run the sandbox checks on a real gateway.
• Agent. Build the new image, confirm the program's real path, compare the vendor's profile with our reviewed copy, and run the four checks in What supported means.

On Team

Each enrolled machine reports its runtime version and sandbox driver. The console lists them, so you can see which machines still run an older runtime before you rely on a newer one.