Skip to content

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.

Start the VM and wait until Docker reports ready:

Terminal window
kat start

You 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:

Terminal window
kat status

The output shows the VM state, CPU count, memory limit, Docker readiness, ~/Katamaran mount status, and forwarded ports.

Create a scratch directory on your Mac with a sample file:

Terminal window
mkdir -p ~/katamaran-demo
printf 'hello from macos\n' > ~/katamaran-demo/index.html

Start an Alpine container that binds ~/katamaran-demo at /site and serves it on port 8080 without a -p flag:

Terminal window
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:

Terminal window
curl http://127.0.0.1:8080/index.html

You should see:

hello from macos

Edit the file on your Mac and request it again:

Terminal window
printf 'updated on macos\n' > ~/katamaran-demo/index.html
curl http://127.0.0.1:8080/index.html

You 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:

Terminal window
docker rm -f demo-web
rm -rf ~/katamaran-demo

Create an Ubuntu machine named dev:

Terminal window
kat machine create dev

Wait for the image download and first boot to finish. Open an interactive shell in dev:

Terminal window
kat shell dev

You are logged in as a user with your macOS username. Check the OS release, then exit the shell:

Terminal window
cat /etc/os-release
exit

List your machines to confirm dev is running:

Terminal window
kat machine list

If you no longer need dev, delete it:

Terminal window
kat machine delete dev