Quickstart tutorial
In this tutorial, you start the katamaran VM, serve a file from your Mac inside a container, verify live file changes, and open a shell inside an Ubuntu Linux machine.
Make sure you have completed Install katamaran before starting.
1. Start the VM
Section titled “1. Start the VM”Start the VM and wait until Docker reports ready:
kat startYou should see confirmation that the daemon and Docker are ready. Both kat start and launching Katamaran set the active Docker context to katamaran automatically. Check the VM state:
kat statusThe output shows the VM state, CPU count, memory limit, Docker readiness, ~/Katamaran mount status, and forwarded ports.
2. Run a container with a bind mount
Section titled “2. Run a container with a bind mount”Create a scratch directory on your Mac with a sample file:
mkdir -p ~/katamaran-demoprintf 'hello from macos\n' > ~/katamaran-demo/index.htmlStart an Alpine container that binds ~/katamaran-demo at /site and serves it on port 8080 without a -p flag:
docker run -d --rm --name demo-web -v ~/katamaran-demo:/site alpine:3.24 sh -c 'cd /site && exec httpd -f -p 8080'Because automatic port forwarding is enabled by default, request the file from your Mac at 127.0.0.1:8080:
curl http://127.0.0.1:8080/index.htmlYou should see:
hello from macosEdit the file on your Mac and request it again:
printf 'updated on macos\n' > ~/katamaran-demo/index.htmlcurl http://127.0.0.1:8080/index.htmlYou should see updated on macos immediately. macOS FSEvents invalidates the guest’s cached file metadata and data on every host change.
Stop the container and remove the scratch directory:
docker rm -f demo-webrm -rf ~/katamaran-demo3. Create a Linux machine
Section titled “3. Create a Linux machine”Create an Ubuntu machine named dev:
kat machine create devWait for the image download and first boot to finish. Open an interactive shell in dev:
kat shell devYou are logged in as a user with your macOS username. Check the OS release, then exit the shell:
cat /etc/os-releaseexitList your machines to confirm dev is running:
kat machine listIf you no longer need dev, delete it:
kat machine delete devNext steps
Section titled “Next steps”- Read Use Docker for Compose, storage, and socket details.
- Read File sharing to inspect Linux files in Finder and tune bind mounts.
- Read Configuration reference to adjust CPU, memory, and sleep settings.