Sandbox management

Use mvmctl when you need the local management layer for sandboxes.

Create or boot

mvmctl init ./agent-sandbox --preset python
mvmctl build ./agent-sandbox
mvmctl up ./agent-sandbox --name agent-sandbox

mvmctl build uses the builder VM for Linux image construction. mvmctl up boots the runtime guest from the built artifact.

Inspect

mvmctl ls
mvmctl boot-report agent-sandbox
mvmctl logs agent-sandbox

Use JSON output where commands support it when integrating with tooling.

Operate

mvmctl exec agent-sandbox -- python /work/task.py
mvmctl fs ls agent-sandbox /work
mvmctl forward agent-sandbox -p 8080:8080

Command execution, file operations, and port forwarding cross trust boundaries. Keep command args explicit, file paths narrow, and ports intentional.

Preserve state

mvmctl pause agent-sandbox
mvmctl resume agent-sandbox

For backend-specific machine-state files:

mvmctl snapshot save agent-sandbox --path /tmp/agent-sandbox.vzsnap --hypervisor vz
mvmctl snapshot restore agent-sandbox --path /tmp/agent-sandbox.vzsnap --hypervisor vz

Snapshots can contain memory, files, and runtime credentials. Apply retention and deletion policy.

Stop and clean up

mvmctl down agent-sandbox
mvmctl cleanup

Stopping compute is not the same as deleting all state. Check manifests, volumes, snapshots, and cache entries when you need stronger cleanup.