Skip to content
Tormoni

Running a sandbox

A sandbox with no flags gets three things: its root image, read-only; loopback; and one empty directory at /results for what it produces. Nothing else is shared. Everything past that is opted into on the command line, and the posture is printed, because what is shared is the policy — there is no in-kernel enforcer behind it to decide anything later.

Terminal window
tormoni run --root ~/.local/share/tormoni/rootfs -- uname -a

The guest root falls back to $TORMONI_GUEST_ROOT, then ~/.local/share/tormoni/rootfs, so after one cargo xtask init the --root flag can be dropped.

The posture flags

Section titled “The posture flags”

These flags define the permissions and capabilities of a sandbox. They apply when you use commands like run, shell, and up. The run record keeps track of what was granted.

You can use --dry-run to print the posture without booting anything.

Flag Grants Default
--rootfs writable The guest writes through to the shared image tree. read-only
--net tsi libkrun’s socket impersonation: the guest reaches what the host can. none
--mount GUESTDIR=HOSTDIR A host directory, read-write, at a guest path. Repeatable. nothing
--share TAG=HOSTPATH An extra virtiofs device for a guest that mounts by tag. Repeatable. nothing
--display WIDTHxHEIGHT[@HZ] A virtio-gpu display in a window; closing the window stops the sandbox. none
--sound A virtio-snd card on the host’s audio server: playback and capture. off
--gpu A 3D virtio-gpu into the host renderer; the guest brings its own driver. off
--env KEY=VALUE One guest environment entry. Repeatable. nothing
--vcpus N, --mem MIB Sizing; also $TORMONI_VCPUS and $TORMONI_MEM_MIB. 1 vCPU, 512 MiB
--no-results Drops the default /results mount. mounted

Two of these widen what the sandbox costs you rather than what it grants the guest — --display and --gpu both bring the host GPU into the picture. Sandbox security explains how this affects the trust boundary.

This page is a summary. The book’s Running a sandbox page is the authority on every flag above, and it changes without notice while the sandbox is pre-v0.1.0 — believe it over this page.