Docker Backend

The Docker backend runs Mona's terminal commands inside a Docker container. This provides strong isolation — if a command is destructive or malicious, only the container is affected.

When to use Docker

• Running untrusted code — Web searches that download and execute scripts
• Multi-user deployments — Shared servers where users shouldn't access each other's files
• Reproducibility — Commands run in a clean, consistent environment
• Safety — Protection against accidental rm -rf /

Setup

1. Install Docker

Get Docker for your platform.

2. Configure MonoClaw

monoclaw config set terminal.backend docker

Or in config.yaml:

terminal:
  backend: docker
  docker:
    image: "ubuntu:24.04"
    network: bridge
    volumes:
      - "${HOME}/projects:/projects"
    workdir: "/projects"

3. Verify

monoclaw doctor

Look for the Docker backend check.

How it works

When Mona needs to run a command:

1. MonoClaw spins up a Docker container from the configured image
2. The command executes inside the container
3. Output streams back to Mona in real time
4. The container stops when idle (or stays running for performance)

Custom images

Build a custom image with your preferred tools:

# Dockerfile.monoclaw
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y \
    git python3 nodejs ripgrep ffmpeg \
    build-essential curl wget \
    && rm -rf /var/lib/apt/lists/*
WORKDIR /projects

docker build -t monoclaw-env -f Dockerfile.monoclaw .

# config.yaml
terminal:
  backend: docker
  docker:
    image: "monoclaw-env:latest"

Volume mounting

Mount your project directory so Mona can access files:

terminal:
  docker:
    volumes:
      - "${HOME}/projects:/projects"
      - "${HOME}/.ssh:/root/.ssh:ro"

Network isolation

Control container network access:

terminal:
  docker:
    network: none      # No internet access
    # or
    network: bridge    # Default NAT
    # or
    network: host      # Share host network (less isolated)

Running the full agent in Docker

You can also run the entire MonoClaw runtime inside Docker:

docker run -it \
  -v ~/.monoclaw:/root/.monoclaw \
  -v $(pwd):/projects \
  -w /projects \
  monoclaw-runtime:latest \
  monoclaw

This is useful for:

• Testing in a clean environment
• CI/CD pipelines
• Deploying to cloud containers

Performance tips

• Keep containers warm — Set keep_warm: true to avoid container startup latency
• Use smaller images — Alpine or slim variants start faster
• Pre-install tools — Include ripgrep, git, and node in your image
• Volume caching — Mount dependency caches (npm, pip) for faster installs

Troubleshooting