Use Docker
katamaran runs containerd and dockerd inside the Linux guest and relays the Docker Unix socket to macOS over virtio-vsock.
Select the Docker context
Section titled “Select the Docker context”Launching Katamaran or running kat start creates the katamaran Docker context and sets it as the default automatically. To target it for a single command when another context is active:
docker --context katamaran psTo switch back manually:
docker context use katamaranFor tools that ignore Docker contexts and read DOCKER_HOST, export the socket path:
export DOCKER_HOST="unix://$HOME/.katamaran/run/docker.sock"When KATAMARAN_HOME is set to a custom directory, the socket lives at $KATAMARAN_HOME/run/docker.sock.
Run Docker Compose
Section titled “Run Docker Compose”docker compose inherits the active Docker context or DOCKER_HOST. Run it from any project directory under /Users:
docker compose up -ddocker compose psdocker compose downRelative bind mounts such as .:/app resolve against /Users, which katamaran shares into the guest at the same path.
Understand Docker storage inside the VM
Section titled “Understand Docker storage inside the VM”The guest uses a read-only EROFS system image as the lower layer of an overlay root filesystem, paired with a sparse btrfs data disk at ~/.katamaran/data/data.img. The data disk holds three btrfs subvolumes mounted with noatime and discard=async:
| Subvolume | Guest mount path | Purpose |
|---|---|---|
docker |
/var/lib/docker |
Docker runtime state, networks, and volumes |
containerd |
/var/lib/containerd |
Containerd image store and overlayfs snapshots |
katamaran |
/var/lib/katamaran |
Linux machines and persistent guest state |
Docker runs with the containerd image store (containerd-snapshotter: true) and the overlayfs snapshotter. Periodic FITRIM discards unused blocks on the btrfs data disk so the sparse data.img file on APFS shrinks as you prune unused images and containers.
Reclaim unused Docker storage inside the guest with standard Docker commands:
docker system dfdocker system pruneTune Docker daemon resources
Section titled “Tune Docker daemon resources”Docker uses the vCPUs and memory ceiling configured for the katamaran VM. Change them and restart the VM:
kat config set cpus=8 memory=12Gkat restartSee Configuration reference for all VM settings.