Linux machines
A Linux machine in katamaran is a full Linux system (an LXC container) running inside the katamaran VM with systemd or OpenRC, its own network address, and your macOS username preconfigured.
Create a machine
Section titled “Create a machine”Create and start an Ubuntu machine named dev:
kat machine create devSpecify another distribution with --distro (-d) and an optional release with --version (-r):
kat machine create box --distro alpinekat machine create fed --distro fedorakat machine create deb --distro debian --version bookworm--distro accepts ubuntu, debian, alpine, fedora, arch, or any distribution published on images.linuxcontainers.org.
List and manage machines
Section titled “List and manage machines”kat machine listkat machine list --jsonkat machine info devkat machine default devkat machine stop devkat machine start devkat machine delete devMachines that are running when the VM shuts down start automatically the next time the VM boots. Running kat machine stop <name> stops the machine and turns off autostart until you start it again.
Open a shell or run a command
Section titled “Open a shell or run a command”Open an interactive login shell in the default machine or a named machine:
kat shellkat shell devRun a single command without starting an interactive shell:
kat shell dev -- uname -aLog in as another user, such as root:
kat shell dev -u rootConnect over SSH
Section titled “Connect over SSH”katamaran ships an integrated SSH proxy (katamaran ssh-proxy) so standard ssh, scp, sftp, VS Code Remote SSH, and rsync work without managing authorized keys manually.
- Run
kat setupif you have not done so yet. - Add the
Includeline printed bykat setupat the top of~/.ssh/config:
Include ~/.katamaran/ssh/config- Connect with
sshorkat ssh:
ssh dev@katamaranssh root@dev@katamaranssh katamarankat ssh devkat ssh dev -- ls -lassh <machine>@katamaranconnects to<machine>as your Mac user.ssh <user>@<machine>@katamaranconnects as<user>.ssh katamaranconnects to the default machine.
katamaran generates and pins a host key under ~/.katamaran/ssh/ on first use.
Ports and files in machines
Section titled “Ports and files in machines”- TCP ports that a machine listens on across all addresses (
0.0.0.0or::) are forwarded to127.0.0.1on macOS automatically, unless the root namespace already owns that port. - Each machine’s filesystem is visible on macOS at
~/Katamaran/machines/<name>when NFS mounting is enabled.