Skip to content

Command-line reference

kat is a symlink to katamaran created by kat setup. Every command below works with either name.

Start the VM (starting the daemon first if needed) and wait until Docker answers.

Terminal window
kat start [--timeout <SECONDS>]
Option Default Description
--timeout <SECONDS> 180 Maximum seconds to wait for Docker to become ready

Stop the VM cleanly. The background daemon keeps running.

Terminal window
kat stop

Stop the VM and start it again so saved configuration changes take effect.

Terminal window
kat restart [--timeout <SECONDS>]

Print the VM state, CPU and memory limits, Docker status, NFS mount path, and forwarded ports.

Terminal window
kat status [--json]
Option Description
--json Emit the full status payload as JSON

Print logs from the daemon, the guest console, the VM monitor, or gvproxy.

Terminal window
kat logs [-f] [-n <LINES>] [--source <SOURCE>] [--console]
Option Default Description
-f, --follow off Stream new log lines as they arrive
-n, --lines <LINES> 100 Number of lines to print from the end
--source <SOURCE> daemon Log stream (daemon, console, vm, or gvproxy)
--console off Shorthand for --source console

Print the CLI version and the running daemon version.

Terminal window
kat version

Print every setting in ~/.katamaran/config.toml, or print one key.

Terminal window
kat config get [KEY]

Update one or more settings and validate them against the Mac’s hardware limits. Changes apply on the next VM start (except launch_at_login, which updates the LaunchAgent immediately).

Terminal window
kat config set cpus 6
kat config set cpus=6 memory=8G mount=off

See Configuration reference for every valid key and value format.

Install the LaunchAgent, the Docker context, the SSH config files under ~/.katamaran/ssh/, and the ~/.local/bin/kat symlink.

Terminal window
kat setup [--default] [--suffix <SUFFIX>]
Option Description
--default Set the katamaran Docker context as the active default
--suffix <SUFFIX> Suffix for the LaunchAgent label, Docker context, and symlink

Remove the LaunchAgent, Docker context, and kat symlink installed by kat setup. Stored VM data under ~/.katamaran is preserved.

Terminal window
kat uninstall [--suffix <SUFFIX>]

Manage the coding-agent skill for Claude Code (~/.claude/skills/katamaran) and Codex, OpenCode, and Pi (~/.agents/skills/katamaran). Installed agents receive a small stub that runs kat skill show, so upgrading katamaran updates the guide automatically.

Terminal window
kat skill setup [--agent claude|agents]
kat skill show
kat skill status [--agent claude|agents] [--json]
kat skill remove [--agent claude|agents]

Download an image if needed, create an LXC machine, and start it.

Terminal window
kat machine create <NAME> [-d <DISTRO>] [-r <VERSION>]
Option Default Description
-d, --distro <DISTRO> ubuntu Distribution (ubuntu, debian, alpine, fedora, arch, or any image on images.linuxcontainers.org)
-r, --version <VERSION> current release Specific release name or version (for example noble or 3.24)

List all Linux machines and their states.

Terminal window
kat machine list [--json]

Start a stopped machine (defaults to the default machine if NAME is omitted).

Terminal window
kat machine start [NAME]

Stop a running machine and disable its autostart on VM boot.

Terminal window
kat machine stop [NAME]

Stop and permanently delete a machine and its root filesystem.

Terminal window
kat machine delete <NAME>

Display metadata, IP address, and state for one machine.

Terminal window
kat machine info [NAME]

Print the current default machine, or set a new default machine.

Terminal window
kat machine default [NAME]

Open an interactive login shell or run a command inside a Linux machine.

Terminal window
kat shell [-u <USER>] [MACHINE] [-- <CMD>...]
Option Default Description
-u, --user <USER> your Mac user Linux user to run as

Connect to a Linux machine through katamaran’s managed SSH configuration.

Terminal window
kat ssh [DEST] [-- <CMD>...]

DEST is <machine> or <user>@<machine>. Omit DEST to connect to the default machine.

Run one VM directly in the foreground without the LaunchAgent daemon until interrupted with Ctrl+C or SIGTERM.

Terminal window
katamaran run [OPTIONS]
Option Default Description
--cpus <CPUS> 4 Number of vCPUs
--memory-mib <MIB> 16384 Guest memory ceiling in MiB
--kernel <PATH> guest/out/Image Path to uncompressed arm64 kernel image
--initramfs <PATH> guest/out/initramfs.cpio Path to initramfs archive
--rootfs <PATH> guest/out/rootfs.erofs Path to read-only EROFS system image
--data-template <PATH> guest/out/data.img Path to template btrfs data disk
--cmdline <ARGS> empty Extra Linux kernel command-line arguments
--vm-bin <PATH> sibling katamaran-vm Explicit path to the katamaran-vm binary
--no-share off Do not share /Users into the guest
--permissions <MODE> caller Host file permission mode (caller, caller-uncached, fixed, or xattr)
--mount <PATH> ~/Katamaran Host mount point for Linux NFS files
--no-mount off Disable the macOS NFS mount
--no-network off Boot without a virtio-net device
--gvproxy <PATH> in-process libgvproxy.dylib Run an external gvproxy binary instead of loading libgvproxy.dylib
--mtu <BYTES> 65520 MTU of eth0 and Docker bridges
--pause-on-sleep off Freeze vCPUs while macOS sleeps
--no-auto-forward off Disable forwarding of unpublished container ports
--amd64 <MODE> auto x86-64 emulation (auto, rosetta, qemu, or off)

Run the background daemon owned by launchd. You do not normally invoke this directly.

Boot a throwaway VM, print per-stage kernel and init boot timings, and power it off immediately.