Mounts and worktrees

Shadow disks do not apply to mounts

Shadow disks are built, but they attach to a captured --workspace, not to a --mount. On a live virtiofs mount the shipped path for dependency isolation (node_modules, build caches, etc.) is --mount-named kind=disk — see Volume commands and CLI — Named volumes.

Mount a host git worktree as the live workspace — edits inside the sandbox appear on the host immediately, and work flows back through normal git push.

Live virtiofs mounts replace workspace capture. There is no archive step and no extraction step.

1. Create a dedicated git worktree

git -C /data/repos/myrepo worktree add /data/repos/myrepo-dev1 feat/my-branch

2. Boot the sandbox with the worktree attached

nexus create myproject/dev-1 \
  --context /data/repos/myrepo-dev1 \
  --mount /data/repos/myrepo-dev1:/workspace/myrepo \
  --memory 8192

partial — current implementation uses nexus sandbox create and --file; see CLI sandbox commands for the mapping.

--context locates .nexus/Containerfile for the rootfs build. --mount host-path:guest-path (repeatable; add :ro for read-only) attaches the host directory as a live virtiofs mount at the guest path. The host path must exist and be a directory; it is resolved to an absolute path.

Git identity in mounted worktrees

When a host git worktree is mounted into the sandbox, git operations inside the guest use the repo-local git config from .git/config in that repository — not the host's global ~/.gitconfig. This means:

• user.name and user.email set via git config --local in the worktree apply in-guest automatically.

• The host's ~/.gitconfig does not reach the guest unless you mount it explicitly:

  nexus create myproject/dev-1 \
    --mount /data/repos/myrepo:/workspace/myrepo \
    --mount ~/.gitconfig:/root/.gitconfig:ro \
    --image nexus-base:20260807

  This is optional — if the worktree's repo-local config already has the identity you want, no extra mount is needed.

3. Run work inside the sandbox

nexus exec myproject/dev-1 -- go test ./...
nexus exec myproject/dev-1 -- git add -A
nexus exec myproject/dev-1 -- git commit -m "feat: implement foo"

Every write inside the guest appears in the host worktree immediately — no sync step.

4. Push from the host

Credentials stay on the host, not in the guest:

git -C /data/repos/myrepo-dev1 push origin feat/my-branch

Multiple mounts are also supported — for example, a read-only shared config alongside a writable source tree:

nexus create myproject/dev-1 \
  --context /data/repos/myrepo \
  --mount /data/repos/myrepo:/workspace/myrepo \
  --mount /data/shared/secrets:/run/secrets:ro \
  --memory 8192

partial — current implementation uses nexus sandbox create and --file; see CLI sandbox commands for the mapping.

---

Shadow disks built

Write-heavy paths (package managers, build caches, compiler outputs) amplify the cost of a captured workspace disk. A shadow disk backs one such path with a per-sandbox sparse ext4 virtio-blk image that lives entirely inside the guest's disk space, so those writes never land on the workspace disk.

Shadow disks attach to --workspace, not to --mount. A sandbox created with --mount gets no shadow disks at all. This section is here because the two mechanisms are easy to confuse; if you are mounting a worktree, use named volumes instead (see the note at the top of this page).

Default shadow paths built

Every --workspace sandbox gets exactly these four, relative to the workspace root:

Guest path (relative to workspace root)	Typical owner
node_modules	npm / pnpm / yarn
.next	Next.js build cache
target	Rust / Maven / Gradle
dist	bundlers

The guest sees these as ordinary directories; the shadow binding is transparent to all tooling.

Declaring additional shadow paths not built

The set above is fixed. There is no flag to add or remove a shadow path — the design called for one and it was never built, so a monorepo with nested packages/*/node_modules gets shadow disks only at the top level. Use --mount-named kind=disk to isolate a nested path today.

Shadow disk lifecycle

Event	Workspace disk	Shadow disks
create --workspace	created from host dir	created as empty sparse images
stop	persisted	persisted
rm	deleted	deleted

Shadow disks do not survive rm — Service.Remove calls ReapShadowDisks for the sandbox's handle. Build artifacts and package trees are ephemeral per sandbox. Durable work flows back via git push, not file copy.

A fork child receives a copy-on-write copy of each of its parent's shadow disks, named <childID>-<parentHandle>.shadow.<name>.ext4, and owns it for as long as the child record lives.

---

Fork and snapshot restrictions

fork and snapshot create are refused on a live-mounted sandbox and return an explicit error naming the offending host→guest pairs.

• Fork refused: two VMs would share one worktree and one .git/index.lock, producing concurrent writes to the same tree with no coordination.
• Snapshot refused: the mounted tree lives on the host and is not captured inside the snapshot; restoring would resume memory state against files that have changed underneath it.

For N-way parallel work, use independent creates — each sandbox gets its own git worktree directory. See Parallel development flow.

---

See also

• Parallel development flow
• Building images
• Surface reference — create