← Docs
vm_sync makes a VM's copy of a git checkout match your local one exactly: the same commit, plus your staged, unstaged and untracked changes. Agents edit locally and run code in the VM; one sync before each run keeps the VM current, without giving the VM GitHub access or carrying patches by hand. It only pushes: nothing comes back from the VM, and there is no watch mode.
boxery sync demo # the checkout you're in → demo:~/project
boxery sync demo --from ../api --to ~/api # another checkout → demo:~/api
boxery sync demo --json # the result as JSON{"vm":"demo"}
{"vm":"demo","from":"../api","to":"~/api"}from is a local directory inside the checkout (default: the agent's working directory, or the CLI's current directory); the whole repository is synced from its root. to is the VM directory (default ~/project; relative paths are under it). boxery sync runs vm_sync's own code (CLI).
- Snapshot. It records local HEAD plus every working change (what
git add -Awould stage: tracked files, and untracked files.gitignoredoesn't exclude, deletions and renames included) as one commit. It uses a scratch index and object directory: your index, refs and stash are untouched. The commit has a fixed author and date, so the same working state always gives the same commit. - Push. The snapshot is
git pushed straight into the VM repository, to a hidden ref (refs/boxery/incoming/…), over the VM's own ssh connection (the host profile'sssh_config, pinned host key). git works out which commits the VM lacks from all of its refs and streams only those intogit receive-pack: no archive, no temporary file. The push reads none of your global or system git config and noGIT_*environment variables, so aurl.insteadOfcan't redirect it. No hooks run on either side. Nothing contacts a git remote, so the VM needs no GitHub grant. If the VM already has the snapshot, nothing is pushed. Iftodoesn't exist or is empty, a repository is initialized there first (after the checks pass), and removed again if the push fails. - Swap. In the VM, HEAD is detached at local HEAD's commit, and the working directory is switched to the snapshot: only the paths that differ are rewritten, and files the snapshot lacks are deleted, including ones an earlier sync put there. Ignored files (
node_modules, build output) stay: there is nogit clean -x. If the snapshot would put a tracked file where the VM has an ignored one, the sync refuses instead (below). The VM's index holds HEAD, sogit statusandgit diffin the VM show the same working changes as they do locally. - Check. Both sides hash the whole working directory (tracked plus untracked, not ignored) as a git tree, the same way, and compare. The result says
tree matches, orTREE MISMATCH(an error).
synced 3f2a9c1 + 2 modified, 1 untracked, 0 deleted → demo:/home/agent/project · tree matches
Structured fields: sha (local HEAD), snapshot, counts (modified, untracked, deleted), tree (local, vm, match), lockfile_changed, pushed (false when the VM already had the snapshot), objects_sent, elapsed_ms.
lockfile_changed is true when pnpm-lock.yaml, package-lock.json, yarn.lock or bun.lock (at any depth) differs from the previous sync, or from the VM's HEAD on the first one. vm_sync installs nothing; run your install step when it says so.
A second sync with no local changes sends nothing and still reports tree matches.
It refuses, and changes nothing in the VM, when:
- The VM checkout has changes the last sync didn't make. The VM records each sync in
refs/boxery/synced(and local HEAD inrefs/boxery/base). Any difference between the VM's working directory and that snapshot (edited, new or deleted files, not ignored ones) is listed in the error. Commit them in the VM and bring them back yourself, or discard them, then sync again. A VM repository that was never synced is compared with its HEAD. - The checkout holds a credential file. Matched case-insensitively:
.envand.env.*/.env-*/.env_*(except.env.example,.env.sample,.env.template,.env.dist,.env.defaults),.envrc,.npmrc,.yarnrc.yml,.pypirc,.netrc,.git-credentials,.pgpass,.my.cnf,.terraformrc,auth.json,credentials,application_default_credentials.json, private keys (id_*except.pub,*.pem,*.key,*.p12,*.pfx,*.jks,*.keystore),.docker/config.json,.kube/config,.aws/config,gh/hosts.yml, and anything inside boxery's own state or~/.ssh,~/.gnupg,~/.pi(whatvm_copyrefuses). The error names the path. Ignore it in.gitignoreto sync the rest, and get the credential to the VM with a grant, which keeps it off the VM's disk and out of its snapshots. Ignored files are never synced, so an ignored.envis fine. - The commits it would send contain one. The push carries every commit the VM lacks (on a first sync, the whole history), so a credential file committed once and deleted later (merges included) is refused too. Remove it from history first. Which commits the VM lacks is worked out from the refs the VM reports, so this check trusts the VM's report.
- The local checkout now tracks a path the VM has as an ignored file (a force-added build file, or
dist/un-ignored and replaced by a file): the swap would overwrite or delete the VM's file. Or, with the new.gitignore, files the VM has stop being ignored, so the trees can't match. The error lists the paths; remove them in the VM (or change the local checkout), and sync again. tois a non-empty directory that isn't a git repository, is inside another checkout (~/project/apiwhen~/projectis a repository: use~/api), or its object format (sha1/sha256) differs.- The local path isn't a git checkout, has no commits yet, or is a shallow or partial clone. Use
vm_copyfor plain files.
"Nothing changed" means the checkout. A first sync into a missing directory can leave its parent directories behind.
Cancelling (an MCP cancellation, pi's Escape, Ctrl-C for boxery sync) before the push finishes leaves the VM unchanged: git receive-pack keeps incoming objects in a quarantine directory until the ref update succeeds, and removes it when the push dies. Once the VM starts applying, it ignores signals and finishes or rolls back; a lost connection doesn't interrupt it, and boxery sync waits for its result after Ctrl-C.
The swap is staged: the pushed objects are already in the VM's object store (which changes no files); apply writes a pending record, switches the working directory, and finally updates HEAD and its refs in one transaction. If a step fails, it switches back and restores the index. If the VM crashes mid-swap, the next sync finds the pending record and finishes it (if the refs were written) or undoes it, before checking for VM-side changes. It undoes it only if every file is as the swap left it; a file edited since is reported, and the record stays. Pushed objects stay in the VM's repository either way; they're harmless and git gc collects them.
A sync takes a lock in the VM repository (flock, or a lock directory without it), so two syncs into one checkout run one after the other. If the checkout changes between the check and the swap, the sync refuses: git checks every path before writing any.
- Needs git (2.31+) on both sides; boxery's images have it.
- Submodules are synced as gitlinks (their commit ids), not their contents.
- Git LFS files arrive as pointer files: the VM doesn't download them, since vm_sync never contacts a remote.
- Untracked files are hashed into a temporary directory on the local machine, so a very large one needs that much space there.
- Ignore rules that exist only on your machine (
core.excludesFile,.git/info/exclude) aren't sent: files the VM produces that only those rules ignore show up as VM changes, and the sync refuses. Put such patterns in.gitignore. - Executable bits and symlinks follow git's rules; other file modes, owners and timestamps aren't carried.
- The VM keeps every synced snapshot's objects until
git gc. - On an HTTP MCP server,
vm_syncreads checkouts on that server, so it followsvm_copy'slocal:rule: refused without--copy-root, and confined toDIRwith it (MCP server). Confined, the repository's git directory, object store and alternates must be insideDIRtoo, git doesn't look for a repository aboveDIR, and it runs none of the checkout's hooks, fsmonitor or filter drivers.