Docker Compose

Run the whole stack locally¶

Docker Compose is the recommended way to run Mewbo persistently. Prebuilt images ship from GHCR, and one docker compose up starts every service listed below.

Quick Start¶

Copy the template, set three values in it, then pull and start.

cp .env.example .env

MEWBO_MASTER_API_TOKEN=your-strong-random-token
MEWBO_VITE_API_KEY=your-strong-random-token   # must match MEWBO_MASTER_API_TOKEN
MEWBO_HOST_UID=1000                            # output of `id -u`

docker compose pull && docker compose up -d

The console runs at http://localhost:3001, the API at :5125, and the MCP server at :5127.

Environment Variables¶

Every compose service reads .env through env_file: ${MEWBO_ENV_FILE:-.env}. The MEWBO_ prefix stops a collision with a same named variable in your shell or CI. The two MONGO_INITDB_ names stay bare because the official mongo image reads them, not Mewbo.

The console's host port is fixed at 3001. It uses host networking rather than a port mapping, so there is no PORT variable.

LLM provider keys, Langfuse credentials and other runtime settings belong in configs/app.json, not .env. See Configuration.

Referencing .env from configs/app.json¶

A configs/app.json value can name an environment variable instead of embedding a literal. Write ${VARIABLE_NAME} as the whole value, and the secret never has to be written into the file.

{ "api": { "master_token": "${MEWBO_MASTER_API_TOKEN}" } }

A named variable that is not set is refused at startup rather than silently read as empty. One set to the empty string resolves to empty, since it is set. Every key that accepts this is marked in Configuration.

Services¶

The Compose file defines six services.

api, mewbo-mcp and console use host networking, so they share 127.0.0.1 with the host. That is how api reaches mewbo-ide at http://127.0.0.1:5128. ide-proxy sits on the separate mewbo-ide bridge network, loopback bound, to reach the code-server containers the broker attaches there.

mewbo-mcp reads the same .env and mounts the same api-data volume, so it shares the master token and the key store. Keys issued via POST/api/keys work on the MCP server too.

Named Volumes¶

All named volumes survive docker compose down. Only docker compose down -v or docker volume rm clears them.

Mounting Project Directories¶

Mount your project directories through a docker-compose.override.yml, which Compose loads automatically.

cp docker-compose.override.example.yml docker-compose.override.yml
# Edit to add your project paths

Example docker-compose.override.yml

services:
  api:
    volumes:
      - ./docker/init.d:/app/docker/init.d:ro
      - /home/you/Projects/my-project:/home/you/Projects/my-project
      - /home/you/Projects/another-repo:/home/you/Projects/another-repo

Post-Init Scripts¶

Scripts in docker/init.d/ run inside the api container before Gunicorn starts, in filename order. They are sourced rather than executed, so they can export environment variables into the API process. A failing script logs a warning and lets startup continue.

The CLIs install here rather than in the Dockerfile because identity arrives at runtime, not at build time.

To add your own, mount docker/init.d/ as shown above and drop .sh files in. No rebuild is needed.

A common addition trusts a private root CA. Drop the PEM at /usr/local/share/ca-certificates/<name>.crt, keeping the required .crt extension, run update-ca-certificates, then export REQUESTS_CA_BUNDLE and SSL_CERT_FILE so git clone and Python HTTPS clients verify against it.

Runtime Config Injection¶

The console image generates runtime-config.js at container startup from MEWBO_VITE_API_BASE_URL and MEWBO_VITE_API_KEY. Update .env and run docker compose up -d to change the API URL or key. No rebuild is required.

Web IDE¶

The api container has no access to /var/run/docker.sock and no Docker tooling, because it runs the agent's arbitrary shell tool. Daemon access there would let any shell command reach the whole host as root through docker run -v /:/host.

Spawning the per session code-server container is delegated over HTTP to the mewbo-ide broker instead, which accepts only a workspace path, a TTL and a password, never an arbitrary container spec. The API takes this path once MEWBO_IDE_BROKER_TOKEN and MEWBO_IDE_BROKER_URL are set, already wired in .env and docker-compose.yml. Without a broker it falls back to a local Docker daemon, for local development only.

Enable it in four steps.

1. Set MEWBO_IDE_BROKER_TOKEN in .env to a strong random secret.
2. Set MEWBO_DOCKER_GID in .env to the GID of the docker group on your host.

   stat -c '%g' /var/run/docker.sock
   

3. Set MEWBO_IDE_ALLOWED_ROOTS in .env to a colon separated list of absolute project paths.
4. Mount each of those paths read only into the mewbo-ide service at the identical path, following docker-compose.override.example.yml. The broker resolves a requested path to its real path in its own mount namespace, so an unmounted path fails validation even when the string is allowlisted.

The broker binds to 127.0.0.1:5128, loopback only, and is never published off host. Anyone who can reach it can ask the daemon to launch an arbitrary container as root.

Lifetimes, resource limits and the endpoint contract live on Web IDE.

Building from Source¶

Build locally instead of pulling from GHCR.

docker compose up --build -d

Images¶

The Services table above names the image for each running container. ghcr.io/bearlike/mewbo-base never runs on its own. It ships Python, Node and the core packages as the build arg for the API and MCP images.

For production TLS, CORS hardening, and observability setup, see Production Setup.