A tiny CLI that runs a command inside a container, against your real files, then throws the container away. Your dev toolchain (and your AI agents) live in the image, not on your machine.
- Keep your machine clean - toolchains live in one image, not on your host.
- No Dockerfile to write - point it at any image and run.
- Throwaway, but your work stays - every dev run is
--rmwith your$HOMEmounted at the same path by default, so files, dotfiles, and build caches persist. Opt out withhome: false;harv sandboxnever mounts$HOME. - One config, every runtime - the same
.harvey.yamlruns natively on Applecontainer(macOS) and Podman (Linux). - Sandbox AI agents -
harv sandboxruns an agent with no$HOMEand no network.
harv # interactive shell in a throwaway container
harv go test ./... # run one command, then discard the container
harv sandbox claude # run an AI agent boxed in: no $HOME, no networkNo existing tool covers this exact combination: Dev Containers are workspace-centric
and have no Apple container support; Distrobox/Toolbx are Linux-host only with
persistent boxes; Apple's container machine is macOS-only and persistent. harv is
the thin layer that unifies throwaway, $HOME-mounted, config-driven runs across both
runtimes. It is a small wrapper over <runtime> run built with
cobra: config in internal/config, runtimes in
internal/runtime, commands in cmd/. No daemon, no persistent-container lifecycle.
Pre-built binary (static, no toolchain needed): grab yours from the latest release and put it on PATH.
# macOS (Apple silicon)
curl -fL -o ~/.local/bin/harv \
https://github.com/bttnns/harvey/releases/latest/download/harv-darwin-arm64
chmod +x ~/.local/bin/harv
# Linux: use harv-linux-amd64 or harv-linux-arm64 insteadFrom source (needs Go):
git clone https://github.com/bttnns/harvey.git ~/Dev/harvey
cd ~/Dev/harvey && make install # builds ~/.local/bin/harv, version-stamped
harvcalls your container runtime on the host, so build it for the host OS. If you compile inside a Linux container, cross-compile for the host, e.g.harv 'make install GOOS=darwin GOARCH=arm64'.
harv # interactive login shell in a throwaway container
harv go test ./... # run one command in a throwaway container
harv 'npm ci && npm test' # quote to chain shell commands
harv serve --name app -p 3000 npm run dev -- -H 0.0.0.0 -p 3000 # browser-facing server
harv enter # persistent "pet" container for this dir, reused across runs
harv doctor # check runtime, image, config, and platformCopy example.harvey.yaml to .harvey.yaml in a project (or
to ~/.config/harvey/config.yaml for a global default) and edit image:. That is the
only required key. See the usage guide for the full command set.
harv sandbox inverts the permissive dev default: the agent gets the same image (or a
dedicated sandbox.image) but none of your host: only the project is mounted, the
network is off, the root filesystem is read-only, and capabilities are dropped. So it
can't read your SSH keys or cloud creds, write outside the project, or phone home.
harv sandbox claude # run an AI coding agent, contained
harv sandbox 'npm test' # run untrusted scripts, containedBecause the container is the boundary, you can run an agent in its most autonomous
mode and inject only the key it needs. One honest tradeoff: the full seal also blocks
the agent's own model API, so cloud-backed agents need sandbox.network opened while
every other lockdown stays. See docs/sandbox.md for the threat
model, per-runtime support, and per-agent recipes.
- Usage guide - configure, every command, servers, dev vs sandbox.
- Sandboxing AI agents - threat model, per-runtime support, recipes.
- Spec - architecture, full config schema, command and driver reference.
- Status - what works today and what's next.
Named for Harvey, my first dog, a beagle, and the best protector and friend I could have asked for. He loved Fred, his stuffed rabbit, and carried him around.