Moochy

Run your agent safely with moochy run

On this page

All guides

Donated tokens come from someone else's machine. A donor, or anyone who took over their machine, could send back a response that tries to make your agent run something harmful, such as a tool call with curl … | sh. Moochy checks every tool call before your agent sees it, but checks can miss things. moochy run adds a second wall: your coding agent, and everything it starts, runs in a sandbox where a bad command cannot reach your files, your keys, or the network.

It is built into the Moochy app. You do not need Docker or any other service.

moochy up                          # once, if the app is not running
cd ~/src/my-project
moochy run -- claude               # or: opencode, aider, goose, any command-line agent
Copy

moochy run finds the project from the git remote of the current directory (or use --repo owner/name), points the agent at Moochy, and starts it. When the agent exits, the sandbox and everything in it are gone.


What the agent can and cannot do

Inside moochy run
Your project Read and write the project's folder (the git worktree). Use --worktree DIR to pick another one
Secrets in the project Hidden: .env and .env.*, *.pem, *.key, id_*, .npmrc, .netrc, .pypirc, credentials*, cloud tool folders (.aws, .gcloud, .azure, .kube, .docker, .ssh), every file ignored by git, and a git config that holds a credential (a token in a remote URL, a CI extraheader). A Unix socket in the project is hidden the same way. The agent sees an empty file in their place, also when it follows a symlink to a hidden file. A file hidden once stays hidden in later runs, even if the agent edits a .gitignore, renames its folder, or moves it into a .git folder (Moochy keeps the list in ~/.config/moochy/state/masks/; delete it to start over). Every other name of a hidden file (a hard link) is hidden too, and a folder Moochy cannot read is hidden whole. The list is made when the run starts: a secret you add to the project during a run is visible to the agent until the next run. If the project is a git repository and git is missing, moochy run refuses to start
Git Read git status, git log, and git diff as usual. Every .git folder is read-only inside by default, so the agent cannot commit, rewrite history, or plant a hook or setting that your own git would run later. You review the changes and commit them yourself after the run. --git-writable lets the agent commit to the project's own repository; every path your git takes settings, hooks or another repository location from stays read-only even then: hooks/, info/, modules/, worktrees/, branches/, remotes/, config, config.worktree and commondir. Moochy creates the missing ones first (empty), and removes the commondir it made (it contains ., which git reads as "this folder") after the run. One gap stays: if the agent leaves a rebase in progress, git rebase --continue runs the agent's todo list, so abort a rebase you did not start. If git metadata changes in a way the sandbox cannot block (a new .git folder created somewhere inside), moochy run tells you after the run so you can review it
The rest of your computer Not there: your real home folder, ~/.ssh, ~/.aws, your keychain, browser profiles, other repositories, and Moochy's own keys and settings do not exist inside. System folders (/usr, /bin, …) are read-only. On Linux only part of /etc is there: what programs need to start, find users and host names, check certificates and show the time (no shadow, sudoers, ssh, machine-id, environment). $HOME and /tmp are empty, private, limited to 2 GiB each, and deleted at the end
Network Nothing except Moochy, and the hosts you allow with --allow-host (below). The agent reaches donated tokens through the usual base URLs; every other address fails
Environment Clean: only PATH, HOME, TMPDIR, USER, TERM, and the Moochy settings for the agent. Your shell's tokens and variables are not passed in
Processes Cannot see or signal processes outside, cannot gain privileges (on Linux it runs as your own user id, never root, with no capabilities), and has limits on memory (8 GiB for the whole run where Linux delegates a cgroup), file size (16 GiB), open files, and process count (on macOS: open files and CPU time only). Stopping moochy run, even with kill -9, stops everything inside. The terminal modes are put back after the run, so an agent cannot leave your terminal without echo

Tool calls from donated tokens only reach agents inside moochy run. If you connect a tool to Moochy without moochy run, it still gets the text of each response, but each tool call is replaced by a visible [moochy] notice. To change this for a project, two settings are needed: the project allows it (Project settings on moochy.dev), and you allow it on this machine with moochy config set allow_unsandboxed_tools owner/name (a comma-separated list of projects). The project's setting alone, which comes from the server, never does it. The app warns you at every start. Use it only if you run your agent in your own sandbox.

Tools installed in your home folder

Agents installed under your home folder (for example ~/.local/bin/claude, or tools from nvm or cargo) are made visible inside, read-only, so they start normally. Secret-shaped files and sockets in those folders are hidden, as in the project. Nothing else from your home folder is.

Build folders

Folders that git ignores and tools need (node_modules, .venv, target, dist, …) stay visible and writable, and git status does not show what changes in them. After the run, moochy run lists the files there that are new or changed and that your machine could run (executable files, and anything in a bin folder such as node_modules/.bin or .venv/bin). Review them before you run a script, a test or a build from that project.

How the agent finds Moochy

Agents work unchanged: inside the sandbox, the standard variables point to Moochy. ANTHROPIC_BASE_URL, OPENAI_BASE_URL, and OPENAI_API_BASE name the local endpoints, and ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, and OPENAI_API_KEY (plus MOOCHY_TOKEN) carry a token made for this run only. That token is the agent's key to Moochy; it works only while the run lasts. No provider API key is ever visible inside the sandbox. MOOCHY_MCP_URL gives the MCP endpoint.

Allowing other hosts

By default the agent can reach nothing but Moochy, so installing packages from inside the run fails. Allow the hosts you need, one --allow-host each:

moochy run --allow-host registry.npmjs.org --allow-host pypi.org --allow-host files.pythonhosted.org -- claude
Copy
  • Each entry is an exact host name: no wildcards and no IP addresses. An invalid entry stops the run before it starts.
  • Only HTTPS on port 443 goes through, by way of a small proxy that moochy run starts (HTTPS_PROXY points to it inside). Plain HTTP is refused.
  • The proxy connects only if every address the name resolves to is public, so an allowed name cannot be pointed at your local network, at Moochy itself, or at cloud metadata.
  • Each refusal is printed as one line, so you can see what the agent tried to reach.

Allow as little as you can: every allowed host is somewhere the agent can send data.

Linux

The sandbox uses Linux user namespaces, Landlock, and seccomp. It needs Linux 5.13 or later with unprivileged user namespaces. On a kernel whose Landlock lacks a layer (TCP port rules, socket and signal scoping, Unix socket rules), each run prints one note that names it; the namespaces and seccomp still apply. Your supplementary groups stay active inside (Linux does not let an unprivileged program drop them), but the files they open are not in the view.

Ubuntu 23.10 and later block unprivileged user namespaces through AppArmor by default. moochy run and moochy doctor detect this and print the exact fix: a small AppArmor profile that allows namespaces for the moochy app only. It looks like this, with the real path of your moochy:

# /etc/apparmor.d/moochy
abi <abi/4.0>,
include <tunables/global>
profile moochy /usr/local/bin/moochy flags=(unconfined) {
  userns,
  include if exists <local/moochy>
}
Copy

Then load it with sudo apparmor_parser -r /etc/apparmor.d/moochy. Do not turn the restriction off for the whole system (kernel.apparmor_restrict_unprivileged_userns=0): that gives the same permission to every program on your machine.

macOS

The sandbox uses macOS's built-in Seatbelt, the same mechanism other coding-agent tools use. Everything is blocked unless allowed: the agent can read system folders and your project, write only to your project and a private scratch folder, and connect only to Moochy on your machine, plus the allowed-hosts proxy when you use --allow-host. Writes to any .git folder are refused, at any depth. A folder that contains a hidden file cannot be renamed or removed during the run (Seatbelt hides files by path). The data and config folders of Homebrew and MacPorts (/opt/homebrew/var, /opt/homebrew/etc, /usr/local/var, /usr/local/etc, /opt/local/var, /opt/local/etc) are not visible, except their certificate bundles. A git config that holds a credential is not readable at all on macOS, so git commands inside fail in that checkout. The agent can use the terminal it was started in, not your other terminal windows. It cannot list other processes or read their arguments and environment (ps fails inside), and cannot run sudo, su, login, crontab, at, write, or wall. With --git-writable, the read-only git paths are refused in any letter case. The agent reaches Moochy through a loopback port that moochy run connects to the app's socket. macOS does not enforce the memory and process-count limits; a run that changes them prints a note.

Windows

Moochy runs on macOS and Linux only.

If the sandbox cannot start

moochy run never falls back to running without a sandbox. It stops and tells you why; moochy doctor shows the same checks.

--unsafe-no-sandbox runs the command with no sandbox at all, after a warning. It exists for debugging Moochy itself. Do not use it with donated tokens.

What moochy run does not change

  • A donor can still return a wrong or low-quality answer. Review the changes your agent makes, as you would with any model.
  • Text in a response can still try to talk you, or your agent, into running something. Inside moochy run the agent cannot do lasting damage; outside it, you are the safeguard.
  • Another program running as your user outside the sandbox could read your project folder while a run is active. The sandbox protects you from the agent, not from malware already on your machine.

This page as Markdown: /docs/run.md · for AI agents: /llms.txt