How to Sandbox Hermes with Colima?

Free, open-source, command-line. Run Hermes inside Colima’s Lima-backed VM on macOS Sonoma — no GUI, no licence to mind.

Ingredients

• A Mac running macOS Sonoma (14)
• Colima — a thin Lima & container runtime wrapper
• The Docker CLI (no Docker Desktop required)
• Hermes
• About 15 GB of free disk

Colima is the answer when you want a real Linux VM with container runtime semantics, but you do not want to install Docker Desktop and you live happily in a terminal. Under the hood it drives Lima (which drives QEMU or the Virtualization.framework), and exposes a docker-compatible socket so you can keep using docker commands.

1 Install Colima and the Docker CLI

brew install colima docker docker-buildx

The docker formula here installs only the CLI — not the desktop product, not the daemon. Colima will provide the daemon.

2 Start the VM with a single scoped mount

mkdir -p ~/hermes-workspace

colima start \
    --cpu 4 \
    --memory 4 \
    --disk 20 \
    --vm-type vz \
    --mount-type virtiofs \
    --mount "$HOME/hermes-workspace:/workspace:w"

What each flag does:

• --disk 20 — the VM’s virtual disk caps at 20 GB.
• --vm-type vz — use Apple’s Virtualization.framework instead of QEMU. Faster, lower RAM, requires Apple Silicon.
• --mount-type virtiofs — the fast file-sharing backend.
• --mount …:w — share only ~/hermes-workspace, with write access. Nothing else from ~ is reachable from inside.

3 Confirm the seam

colima ssh
ls -la /workspace
touch /workspace/from-colima.txt
exit

ls -la ~/hermes-workspace/from-colima.txt

4 Build the Hermes image

Drop this in ~/hermes-image/Dockerfile:

FROM python:3.12-slim-bookworm

ENV PATH=/root/.local/share/fnm:/root/.local/bin:$PATH \
    HERMES_WORKSPACE=/workspace

RUN apt-get update && \
    apt-get install -y --no-install-recommends curl git build-essential ca-certificates && \
    rm -rf /var/lib/apt/lists/*

RUN curl -fsSL https://fnm.vercel.app/install | bash -s -- --skip-shell && \
    /root/.local/share/fnm/fnm install 22 && \
    /root/.local/share/fnm/fnm default 22

RUN git clone https://github.com/NousResearch/hermes-agent.git /opt/hermes && \
    pip install --no-cache-dir -e /opt/hermes

WORKDIR /workspace
CMD ["hermes", "run", "--workspace", "/workspace"]

Build it — the Docker CLI talks to the Colima daemon automatically:

cd ~/hermes-image
docker build -t hermes-sandbox:latest .

5 Run Hermes

docker run -it --rm \
    --name hermes \
    --memory=4g --cpus=4 \
    --read-only \
    --tmpfs /tmp:rw,size=512m \
    --tmpfs /root:rw,size=1g \
    -v /workspace:/workspace \
    hermes-sandbox:latest

Note that the mount source is /workspace, not ~/hermes-workspace. The bind mount the container sees is from inside the Colima VM, where the Mac folder is already mounted at /workspace. Two hops, but the host folder is still the single physical location.

Day-to-day commands

# pause without losing state
colima stop

# resume
colima start

# wipe the VM completely (the Mac folder is untouched)
colima delete

# how much of the 20 GB is actually used
colima ssh -- df -h /

Back to the main recipe

← How to Run Hermes in a macOS Sandbox?

Further reading

• Colima on GitHub
• Lima on GitHub
• Lima documentation