Give agents a machine they can wreck.Keep yours.

Why .git

Git on your machine runs what a repository’s .git/config and hooks name: core.fsmonitor on every git status, hooks on commit. Your editor and prompt run git status on their own, so a VM able to write .git could run commands on your host within seconds, invisible in git diff.

With a Lima that has sshfs.readonlyNames, every .git and .hg in the shares is read-only for the VM, at any depth, enforced on the host by Lima’s SFTP server. The agent reads the history but cannot commit. It is not merged upstream yet (lima-vm/lima#5529), so agent-vm setup offers a build that has it. The shares then use reverse-sshfs, slower on many files (see Node.js), and without sshfs’s cache on the writable ones, so the VM never writes back a file as it was before you changed it: AGENT_VM_SSHFS_CACHE=1 trades that for speed.

brew unlink lima; brew install sylvinus/tap/lima-sylvinus
agent-vm doctor    # where you stand

# let the agent commit anyway
agent-vm --unsafe-writable-git claude

Beyond the name .git

The folder a core.hooksPath points to in a share (.husky for husky) is read-only too, as is a link on the way to it, and the same goes for the repositories in your writable volumes. A folder holding git’s internals (HEAD, objects/, refs/, a config) is a repository under any name: setting safe.bareRepository to explicit in your global git config makes git ignore it, and one in a writable volume is read-only by its name. A config included from a share, a command or a hook git runs from one, or hooks at the top of a share, are the same kind of door.

Before a VM boots with writable shares, agent-vm stops on each of these it finds, and on a Lima without readonlyNames, and asks: Enter, or no terminal, aborts. doctor lists them. --unsafe-writable-git (or AGENT_VM_UNSAFE_WRITABLE_GIT=1 in your shell, never read from the project) lets the agent commit and reopens that path to your host, with a warning on every run.

The Lima build

On Windows, setup downloads it and checks it against checksums pinned in agent-vm. Elsewhere, Homebrew installs it, or build it from source.

A Lima whose answer agent-vm cannot read stops the start with an error, rather than passing for one without readonlyNames.

# back to Homebrew’s Lima
brew uninstall lima-sylvinus && brew link lima

# the Lima build, without Homebrew (needs Go and make)
git clone --depth 1 -b v2.3.0-sylvinus.2 https://github.com/sylvinus/lima
cd lima && make native && sudo make install

Refused directories and files

agent-vm will not share your home directory, /, its own directory, ~/.agent-vm, Lima’s directory, or a directory containing one of them: cd ~ && agent-vm shell would hand the VM your dotfiles and SSH keys.

It never reads a file in the project by its path, since the VM can make it a symlink to any file of yours. Its own git calls in a project refuse a bare repository and run no core.fsmonitor or pager.

--readonly, in detail

--readonly covers every share, rw volumes included: a writable volume containing the project would be a second way in. Whether the host enforces it is read from what Lima reports, never from the guest. Where it would not (reverse-sshfs without readonlyNames, virtiofs under QEMU), the flag is refused.

A running VM in the other mode is restarted, asked first. Declined, or with no terminal, the command fails, so another session’s read-only VM is never made writable under it.

The rule

Anything on your machine that reads the project and acts on what it finds can run what the agent wrote. agent-vm closes git’s doors (see Protecting .git), but cannot lock the files your other tools read without stopping the agent from working.

So on your machine, open the project in your editor and use git in it; run everything else in the VM, with agent-vm run. The lists below are examples, not an inventory.

• Nothing at all: what runs when you cd into the folder, your prompt redraws, your editor opens it. The most dangerous kind.
• Something you do anyway: git commit runs hooks kept in the working tree, docker compose up mounts what the compose file names.
• Running project code: npm test, make, a build. That is the agent’s code: run it in the VM.

Keeping your checkout out of reach

Do not give agent-vm the checkout you work in. Clone the project a second time, run agent-vm there, and git fetch its work into your checkout once you have read the diff. Fetching does not check files out, so the agent’s files reach your working tree only when you merge. This needs a Lima that keeps .git read-only: otherwise the VM can write the clone’s .git, which git then reads.

# once; --no-local copies objects, no hardlinks
git clone --no-local ~/work/app ~/agent/app
# the agent works there
cd ~/agent/app && agent-vm claude
# back in your checkout, when it is done
cd ~/work/app
git fetch ~/agent/app HEAD:agent/review
git diff ...agent/review   # read all of it
git merge agent/review

Editors and agents

A changed tracked file shows in git diff, a new one as untracked; one in an ignored path (node_modules, .venv, target/) shows nowhere.

• VS Code: open agent-vm projects in Restricted Mode, and do not trust a parent folder. A trusted workspace runs project code through tasks and extensions: eslint.config.js, vite.config.ts, build.rs.
• JetBrains IDEs: “Preview in Safe Mode”. A trusted project runs its Gradle or Maven scripts on import.
• Vim: leave exrc off. Neovim and Emacs ask before running project config.
• Agents on your machine run commands from .claude/settings.json hooks, .mcp.json or .cursor/: review those, and treat CLAUDE.md and AGENTS.md as the VM’s writing.

SSH from your machine

Do not connect VS Code Remote-SSH or open-remote-ssh to an agent VM. They run a server in the VM, which root in the VM controls, and the editor on your machine trusts it. Microsoft’s Remote-SSH page says so: “a compromised remote could use the VS Code Remote connection to execute code on your local machine”, and it is by design. Public write-ups show it opening a terminal on the host and running commands there. That removes the boundary agent-vm sets up, which is worse than opening the project in Restricted Mode. JetBrains Gateway does not say it is safer: its security model page says what the backend loads goes to your machine without asking, the backend opens links there (after a prompt), and decides which client version your machine downloads. For language servers and a debugger with the VM’s packages, use agent-vm code.

For scripts, scp or rsync, agent-vm info prints the SSH alias as ssh_host. Put these lines at the top of ~/.ssh/config: a ForwardAgent yes found before them would hand the VM your SSH keys. --ssh-port pins the port for tools that save it.

# top of ~/.ssh/config
Include ~/.lima/*/ssh.config
Host lima-agent-vm-*
  ForwardAgent no
  ForwardX11 no

agent-vm info | grep ^ssh_host   # the alias to use
agent-vm --ssh-port 2222 shell   # a fixed port

Shell, commands, hooks

• direnv only loads an .envrc you allowed, and a change revokes it.
• mise trusts a config by its path, so the agent can change a trusted mise.toml: your shell runs its hooks and sets its env on the next cd, agent-vm’s AGENT_VM_UNSAFE_* variables included. mise settings set paranoid true ties trust to the content.
• npm run, make, ./gradlew, pytest, node_modules/.bin, an activated .venv: each runs files the agent can write. Run them in the VM.
• docker compose up on your machine can mount any folder of yours into a root container. Docker runs in the VM: use it there.
• lefthook and pre-commit keep their commands in the working tree, and husky’s hooks call project scripts: read them in the diff, or commit with --no-verify.

File managers

• macOS: files written through the share carry no quarantine flag, so Gatekeeper does not check an .app, .command or .pkg left there. Do not open them from Finder.
• Windows: Explorer contacts the server named in a .library-ms, .url, .lnk or desktop.ini it displays, sending your NTLM hash (CVE-2025-24054). Keep Windows updated and outbound SMB blocked.
• Linux: KDE’s Dolphin ran commands from a .desktop file in a folder it only displayed (CVE-2019-14744, fixed in KDE Frameworks 5.61).

Terminal escape sequences

What the VM prints reaches your terminal unfiltered, and terminals act on escape sequences. agent-vm cannot filter them without breaking the agents’ full-screen interfaces.

• Clipboard: OSC 52 lets a program set your clipboard, and in some terminals read it. Never allow reads, and check what you paste into a host shell.
• Replies typed for you: a sequence sent just before exit can make the terminal type into your host shell. Some were real bugs (iTerm2 CVE-2024-38396): keep your terminal updated.
• Features that act on your machine: iTerm2 file transfer and triggers, kitty remote control (keep it off), links whose text differs from their target.
• Spoofing: the VM can print a fake host prompt after a fake exit. Check where you are before typing a secret.

Network and ports

The VM reaches the internet and every service on your machine’s loopback, at 192.168.5.2. Lima forwards every port a VM listens on to your 127.0.0.1 when it is free: a VM that listens first on 5432 receives the connections, and passwords, meant for your local Postgres. Blocking this is on the roadmap.

So every VM can reach the editor of every other one. agent-vm code gives each its own password, made in that VM, and its own host name, <vm-name>.localhost: browsers keep cookies per host name and not per port, so a page a VM serves at 127.0.0.1 does not receive the editor sessions of the others. Chrome and Firefox resolve *.localhost themselves; Safari may not, and then 127.0.0.1 in a private window kept for the editor does the same.

That stops a page, not a VM bent on it. A VM can listen on a port Lima forwards to your machine and send your browser to another VM’s host name on that port: the browser hands it that editor’s session, and the VM can use it on the editor’s own port, with its terminals. Keeping VMs out of each other needs network isolation, which agent-vm does not have yet (roadmap). Until then, stop agent-vm code (Ctrl-C) when you are not using it, and treat an editor as reachable from every VM that runs.