Skip to main content
Full local setup on macOS needs a Docker host. Docker Desktop is one option. Colima is a valid, open source alternative to Docker Desktop. Colima runs the Docker daemon in a Linux VM. The Compose services use network_mode: host, so “the host” is that VM, not your Mac. Colima forwards the ports that the VM listens on to your Mac. Three installer defaults assume Docker Desktop. On Colima they behave as follows:

​
Prerequisites

  • Free disk space on the Mac. The service images, the sandbox base image, and the two sandbox templates use about 11 GB before the first agent run. A VM disk grows on the Mac’s disk. When the Mac’s disk fills, the VM’s filesystem records I/O errors that remain after you free space.
  • The same Docker CLI and Compose plugin that the installer requires.

​
1. Start a VM for Druks

If you might be using more than one local instance of Druks, give each installation its own Colima profile. Two local installations cannot share one Docker daemon, because Drukbox, the secrets exchange, and the secrets proxy use fixed host-network ports.
--activate=false keeps your current Docker context. Set DOCKER_CONTEXT in each shell that runs the installer or docker compose for this installation. Omit the flag to make this VM the default context. Colima mounts your home directory into the VM with write access. Thus, the installer’s default paths under ~ work without extra mounts.

​
2. Give Drukbox access to the Docker socket

Read the group of the socket inside the VM:
Colima’s socket belongs to the docker group, for example 991, with mode 660. The installer writes DRUKS_DOCKER_GID=0 on macOS and writes it again on every run. Thus, a change to .env does not last. Add the group in compose.override.yaml in the installation directory before you run the installer. The installer creates this file only when it is absent and never changes it.
Use the number that stat printed.

​
3. Install and verify

Run the installer and the steps in full local setup with DOCKER_CONTEXT set. Then prove the sandbox path:
The sandbox_e2e check creates a real sandbox container through the socket. A wrong group fails this check. Colima’s default bridge gateway is 172.17.0.1. Thus, the default [sandbox].proxy_url works.

​
Ports and exposure

Colima forwards each port that the VM listens on to the Mac. The installer binds the dashboard to 0.0.0.0 on macOS, and Colima then listens on *:8001 on the Mac. The local instance has no browser authentication. Thus, any device that reaches your Mac on your network can open the dashboard. Do not run a local installation on an untrusted network. Two running Colima VMs that both listen on 8001 compete for the same Mac port, and the first one to bind wins. Nothing reports the conflict. Stop one VM, or run the other installation on another dashboard port. To move the dashboard, change DRUKS_WEB_PORT, DRUKS_UPSTREAM, [urls].endpoint, and [sandbox].issuer_url together.

​
Reset a Colima VM

colima delete <profile> keeps the container runtime data disk. The next colima start attaches it again with its images, volumes, and any filesystem damage. To start from an empty daemon, also delete the data:
WARNING: This deletes the Postgres volume of the installation. The installation directory on your Mac remains.