Chopi 🐶

Run an agent or any other command under a macOS sandbox that:

• Confines filesystem access
• Lets the command propose changes to safe write targets as patches you review outside the sandbox
• Restricts outgoing network connections to allowed hosts
• Restricts git pushes to allowed repos (currently GitHub only)
• Hardens git internals

This is not a container- or VM-based solution. Chopi runs the command directly on your machine with your real tools and environment, using the OS's native sandboxing and additional network proxies to put guardrails around it.

Chopi uses Agent Safehouse for building most of the underlying macOS Seatbelt policy, Smokescreen for its CONNECT proxy, and Caddy for its GitHub reverse proxy.

Install

Clone the repo and run the installer:

./install.sh

Before first use, review the configuration.

Configuration

To add or remove allowed domains, edit config/proxy-rules.yaml. You can also modify the list of known denied domains that don't generate alerts -- important for keeping blocked telemetry, auto-updates etc. from spamming you with notifications. You can add and remove domains while the proxy is running and they'll take effect immediately.

To set the GitHub repos allowlist, edit config/github-allowlist. This too takes effect while the proxy is running, without disturbing running chopi sessions. An edit also has the proxy take up a GitHub token that gh has replaced since it started.

To configure the sandbox policy, edit the first two settings in config/sandbox.sh (other settings can be reviewed later):

• CHOPI_SAFEHOUSE_FLAGS: safehouse flags for selecting what preset features and additional filesystem access to enable in the underlying macOS Seatbelt policy; run safehouse --help for the full list of flags and additional ways to configure safehouse which also take effect here. chopi also automatically appends its network protection Seatbelt policy (always last, so it has the final word on network access).
• CHOPI_EXTRA_ENV: extra environment variables for the sandboxed command, passed as literal KEY=VALUE after the --. Use it for vars whose values are fine to be visible for inspection on the command line. You can also forward a host value here with FOO="$FOO". For secrets or anything you'd rather keep off the visible command line, use safehouse's flags --env-pass NAME (forward a host var by name) or --env=FILE (source an env file) in CHOPI_SAFEHOUSE_FLAGS.
• CHOPI_SAFE_WRITE_TARGETS: paths you'd like to allow writing to from inside the sandbox, but which can't be simply trusted to be written by an agent in auto mode, requiring review outside of the sandbox. See Safe write targets below.

Edits to config/sandbox.sh take effect on any following chopi invocations.

Both configuration files are created once on install and then never overwritten, so any edits persist on reinstalls. When updating Chopi, you can examine the templates under config/templates for any upstream changes that you might want to bring in to your local configuration.

Usage

1. Start the outgoing proxy in its own terminal and leave it running:

   chopi-proxy
   

   All chopi sessions share this one proxy. It runs in the foreground so you can watch refused connections. Each denial also pops a macOS notification naming the host. (If the banners don't appear, allow notifications for your terminal in System Settings -> Notifications.) Hosts matching the known denylist are the exception: their denials log a single quiet deny(known) line per proxy run, with no notification.

2. Run your command under the sandbox from another terminal, at the root of the repo you're working on:

   cd ~/path/to/your/repo
   chopi <executable> [args...]
   

   The sandbox grants read/write to your current directory (the workspace) and runs the command there. The workspace must be the root of a git worktree, where chopi's git protections apply; running anywhere else (a subdir, or a non-git directory) is refused, so you can't accidentally run "naked" without them. This does not start the proxy; it fails fast if the proxy isn't already up. This is intentional: this way, denials are always clearly visible in the separate terminal dedicated to running the proxy in the foreground.

   To run a sandboxed command in a separate git worktree instead of the repo root, you can either cd to an existing worktree and launch chopi as usual, or add and setup a new worktree by running chopi in --worktree mode:

   chopi --worktree NAME <executable> [args...]
   

   Run from the root of the repo (or a worktree), this creates a new linked worktree at <repo>/.worktrees/NAME, checks out branch NAME (creating it in case it doesn't already exist), and runs the command with that worktree folder as its workspace. Or, if the worktree at that path already exists, it is reused (on whatever branch or detached HEAD it has checked out), so you can resume previous sessions.

   In both normal and --worktree modes, chopi also isolates the command to a single worktree and applies additional hardening to prevent rogue commands compromising the host system.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗