chock

Chock is a sandbox first AI coding harness. It runs a coding agent inside the operating system's own sandbox, in a throwaway copy of your project, and it writes every turn to a session log you can read afterwards. Chock is written in Zig 0.17 and builds with zig build.

Why

A coding agent runs commands, writes files, and wants to reach the network. Most harnesses ask the agent to be careful. Chock instead takes the boundary out of the agent's hands, and puts it where the agent cannot turn it off. On Linux a tool call gets a user namespace, a mount namespace, a PID namespace, an IPC namespace and an empty network namespace, under Landlock and a system call filter, in a workspace that is a copy. On macOS it gets Seatbelt for paths, for the network and for signals, and Darwin's own resource limits. macOS gives no bind mount and no usable system call filter, so Chock does not claim those two layers there. Your real project is never written by a tool call, unless you approved a workspace bind in write mode. Every layer that confines the call fails the call if it cannot be applied. The limit layer is the one exception: cgroups are best effort, and chock doctor says so on its own row.

The other half is that every action is reviewable. The session log is the session: every turn, every tool call, every approval and every cost is an event in it. What an agent may do is a static table in chock.zon. Chock reads that table from your project before the sandbox exists, and binds the file into the workspace read only, so the agent can read the rules and cannot change them. The answer is written into the log before the act happens, and an approval nobody answers is a refusal.

Features

• Every tool call inside the operating system's own sandbox, with a throwaway workspace. See docs/security/sandbox.md.
• A declarative policy table, per project, that the agent cannot edit, plus an organisation's bundle above it. See docs/configure/policy.md and docs/configure/org.md.
• An agent that can narrow its own policy and cannot widen it again. See docs/configure/policy.md.
• Nix aware tool calls: a project with a flake.nix dev shell gets that shell's closure and nothing else from the store, and the agent can ask for one more program. See docs/operate/toolchains.md and docs/using/nix.md.
• Subagents, bounded in depth and width by the project. See docs/using/subagents.md.
• Session forks at any completed turn, with Git workspace restoration and a warm microVM checkpoint at the latest turn. See docs/using/forks.md.
• Shared Git and overlay diff review, with file and hunk selection, auditable results, and one-command undo without moving your branch. See docs/running.md.
• Notes an agent keeps between sessions, outside your project. See docs/using/memory.md.
• Tools you supply yourself, as WebAssembly. See docs/extend/plugins.md.
• A daemon that owns sessions, and a browser in front of it. See docs/operate/daemon.md.

Providers

• ai&
• Anthropic
• OpenAI through a ChatGPT account
• Any OpenAI compatible endpoint

Install

Release archives and the Nix flake support x86_64-linux, aarch64-linux, and aarch64-darwin. The Darwin build is for Apple silicon.

Download the build for your platform from chock.ws/download. The page links to the release archives and their checksums, and shows how to put the chock binary on your path.

Release assets also include optional chock-<version>-guest-<linux-target> archives for the microVM driver. They contain the architecture-matched kernel and initrd and are separate so an ordinary installation does not download guest images it does not use. See docs/security/microvm.md.

Download SHA256SUMS beside the archive. With the GitHub CLI, first verify that the checksum manifest came from this repository's workflow:

gh attestation verify SHA256SUMS --repo LilithSemi/chock

Then set the archive's exact file name and verify its bytes before unpacking it. Linux commonly provides sha256sum, while macOS provides shasum:

archive=chock-VERSION-PLATFORM.tar.gz
if command -v sha256sum >/dev/null 2>&1; then
  awk -v archive="$archive" '$2 == archive' SHA256SUMS | sha256sum --check
else
  awk -v archive="$archive" '$2 == archive' SHA256SUMS | shasum -a 256 --check
fi

Each release archive also carries signed build provenance. Verify the archive itself before you unpack it:

gh attestation verify chock-<version>-<platform>.tar.gz --repo LilithSemi/chock

With Nix, install the current build from the project's flake into your user profile:

nix profile install github:LilithSemi/chock

Then continue with the configuration and first-run checks below.

Getting started

chock config init                          # save a local-provider starter
chock config check                         # check it before a session
chock models --probe                       # test the provider and list its models
chock doctor                               # can this configuration run here
cd ~/some-project
chock run "add a test for the parser"
chock -- add a test for the parser         # the same task, with no subcommand
chock                                      # the interface, which asks for the task

chock doctor tries each sandbox layer for real and checks the configuration needed for a first session, so run it after creating or linking that file. chock run names the session before it starts, and chock run --verbose adds the session log's path. Bare chock brings up a full screen interface and asks for the task in it.

The starter expects a local OpenAI-compatible server at http://127.0.0.1:5000/v1 with model glm4.7-flash:A3B, and needs no credential. Start that server, or edit the provider and model when you use a different one. Then run chock config check again. When the provider needs a stored login, use chock login --provider KIND --name NAME. Omit --name when the instance name is the same as its kind. chock models --probe tests the endpoint and credential before the first session.

A first word is read as a command name, so a task given on the line goes after --. chock fix the parser is refused, because a typed chock rnu that quietly became a task would spend money on a typo. chock -- fix the parser runs, and so does echo "fix the parser" | chock.

By default, Chock reads ~/.config/chock/config.zon; an absolute XDG_CONFIG_HOME selects a different config directory. chock config init writes a starter only when no configuration exists. chock config path prints the exact XDG-aware location. chock config example prints the same starter without writing it. chock config check validates the result without reading a credential or contacting a provider. chock models shows the effective default, context limit, and adapter capabilities without contacting the provider. Add --probe only when you want an authenticated catalogue request. See docs/configure/configuration.md.

Chock is a pre-alpha project. Its documentation describes the implemented behavior and names platform limits where they apply; the issue tracker holds planned work and known faults.

Documentation

Build with zig build. See docs/ for how Chock works, one page per subject.

Contributing

CONTRIBUTING.md has the repository layout, the coding standards, and the four rules that hold the security model together.

Read SECURITY.md first. It says what Chock protects, what it does not, and how to report a hole in the boundary. The Code of Conduct applies to everyone here.