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.

Every .git and .hg in the shares is read-only for the VM, at any depth, enforced on your machine by the SFTP server built into agent-vm (Lima’s sshfs.readonlyNames, not merged upstream yet: lima-vm/lima#5529). The agent reads the history but cannot commit. The shares 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.

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 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.

Lima, built in

agent-vm builds Lima, its SFTP server (sshocker and pkg/sftp) and its network stack (gvisor-tap-vsock) from their upstream sources, with patches kept small enough to be sent upstream: the read-only names, fixes to the SFTP server (an append that crashed the VM, writes applied out of order), network isolation, the port check. Each running VM is served by an agent-vm process, which is Lima’s host agent.

Every share is served by the built-in SFTP server, confined to its folder: agent-vm starts no VM whose config says otherwise, whatever set it. A default.yaml or override.yaml in ~/.agent-vm/lima/_config would add to every VM’s config, so agent-vm starts no VM while one is there.

Refused directories and files

agent-vm will not share your home directory, /, its own directory, ~/.agent-vm, your own Lima’s directory (~/.lima), or a directory containing one of them: cd ~ && agent-vm shell would hand the VM your dotfiles and SSH keys. --unsafe-disable-security-prompts lets it share its own directory, to work on agent-vm from a clone: the VM can then change the agent-vm your machine runs.

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. The built-in SFTP server enforces it on your machine, and agent-vm checks each VM’s config before it boots, never the guest’s word.

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.

Guarded files

For the first kind, agent-vm guards the files your machine runs on its own: when the VM writes, creates, renames or removes one, at any depth in the shares, a dialog asks you first. A yes holds until the VM stops; a no, for a minute, after which a retry asks again. Where no dialog can be shown (no desktop session), the write is refused and a notification says so; a dialog left unanswered for two minutes refuses it too. AGENT_VM_GUARDED_WRITES=deny refuses them all without asking.

Guarded by default: .envrc (direnv), .vscode/tasks.json, .vscode/settings.json and .vscode/launch.json (VS Code), .pre-commit-config.yaml (pre-commit), lefthook.yml and .lefthook.yml (lefthook), mise.toml and .mise.toml (mise). Files the agent edits as a matter of course, such as a Makefile or package.json, are not: add them in ~/.agent-vm/guarded, one path per line, read when a VM starts. !path removes a default, and *.ext guards an extension. On a Windows host, *.library-ms, *.searchConnector-ms, *.lnk, *.url, *.scf and desktop.ini are guarded too: Explorer sends your NTLM hash to the server they name when it shows them. There is no dialog on Windows, so the VM’s writes to them are refused.

# ~/.agent-vm/guarded
Makefile               # ask before the VM changes any Makefile
.github/workflows/ci.yml
!.vscode/settings.json # no longer asked

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. lima-* also matches the VMs of your own Lima, if you have one. --ssh-port pins the port for tools that save it.

# top of ~/.ssh/config
Include ~/.agent-vm/lima/*/ssh.config
Host lima-*
  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; agent-vm also asks before the VM writes one (Guarded files).
• mise trusts a config by its path: a VM allowed to change a trusted mise.toml makes your shell run its hooks and set its env on the next cd, agent-vm’s AGENT_VM_UNSAFE_* variables included. agent-vm asks before that write; mise settings set paranoid true also ties trust to the content. A config under another name (mise.local.toml, .mise/config.toml) is guarded only once you list it.
• 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: agent-vm asks before the VM changes their config, but not the scripts it names. 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 can contact the server named in a .library-ms, .searchConnector-ms, .lnk, .url, .scf or desktop.ini it displays, and send your NTLM hash (CVE-2025-24054 for .library-ms, CVE-2025-50154 and CVE-2025-59214 for .lnk). Patches have been bypassed before. agent-vm refuses the VM’s writes to these files on Windows; keep Windows updated, outbound SMB (TCP 445) blocked and, where you can, NTLM blocked on the SMB client.
• 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

A VM reaches the internet, not your machine: its loopback (where the other VMs’ ports are forwarded), its own addresses and your local networks (private, link-local and carrier-grade NAT ranges) are refused, on your machine, by the network stack agent-vm runs for each VM. Root in the VM cannot lift it.

There is no ~/.agent-vm/network by default, and none is needed: without it, the VMs reach the whole internet and nothing of your machine or local networks. Write one to open holes, read when a VM starts, one line each: allow an address (192.168.1.20), an address and port (192.168.1.20:5432, [fd00::5]:80), a network (10.8.0.0/16), or a service on your machine’s loopback, localhost:PORT (localhost alone opens every port), which the VM reaches at 192.168.5.2. An allow line covers TCP and UDP.

domain lines restrict the internet itself: those domains and their subdomains (domain github.com covers api.github.com; *.github.com means the same) become the only names the VMs resolve, and an address is reachable once agent-vm’s DNS gave it for one of them. allow lines still apply. A line it cannot read stops the start, named; doctor checks the file. AGENT_VM_UNSAFE_OPEN_NETWORK=1 in your shell turns isolation off.

Each port a VM listens on is forwarded to your 127.0.0.1, and a notification says so, except 32768-60999: the guest gives those to programs asking for any free port (Chromium’s DevTools port, language servers), and they stay inside the VM. A port a program of yours listens on is left to it, with a notification too: on macOS, a VM listening first on 5432 would otherwise receive the connections, and passwords, meant for your local Postgres. On a free port, what you send goes to the VM: check the notification.

No VM reaches the editor of another one any more, but agent-vm code still gives each its own password, made in that VM, and its own host name, <vm-name>.localhost. A VM can serve a page on a forwarded port and send your browser to another VM’s host name on that port; browsers keep cookies per host name and not per port, so the browser hands it that editor’s cookie. The VM cannot use it against the editor itself, being refused your loopback, but stop agent-vm code (Ctrl-C) when you are not using it. 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.

# ~/.agent-vm/network
allow localhost:11434       # Ollama on this machine, at 192.168.5.2:11434
allow 192.168.1.20:5432     # a database on the local network
allow 10.8.0.0/16           # a VPN

# only these on the internet, subdomains included
domain github.com
domain npmjs.org