Run Moltbot with Docker

If you're the kind of person who containers everything, this is your page. Moltbot runs great in Docker. Actually, I'd argue it's one of the best ways to run it if you care about isolation and reproducibility.

You don't need Docker. The npm install works perfectly fine. But Docker gives you some nice things: sandboxed agents, easy cleanup, consistent environments across machines, and a deployment story that doesn't involve thinking about Node.js versions.

Prerequisites

You need Docker installed. Obviously.

• Mac: Docker Desktop for Mac
• Windows: Docker Desktop for Windows (this also needs WSL2, so you'll set up two things at once)
• Linux: Install Docker Engine via your package manager. Don't bother with Docker Desktop on Linux unless you really want the GUI.

Verify Docker is running:

docker --version
docker compose version

Both commands should return version numbers. If docker compose doesn't work, you might have an older Docker version that uses docker-compose (with a hyphen) as a separate binary. Update Docker or install the compose plugin.

Option 1: Docker Build + Run

The simplest approach. Clone the repo and build the image:

git clone https://github.com/moltbot/moltbot.git
cd moltbot
docker build -t moltbot .

This builds a Docker image tagged moltbot. Takes a few minutes the first time because it downloads the Node.js base image and installs dependencies.

Then run onboarding:

docker compose run onboard

This runs the onboarding wizard inside a container. It'll ask you the same questions as the regular onboarding -- API keys, basic settings, etc. Your config gets stored in a Docker volume so it persists between container restarts.

After onboarding, start everything:

docker compose up

That's it. Moltbot is running in Docker. The dashboard should be accessible at http://127.0.0.1:18789/ just like a native install.

Add -d to run in the background:

docker compose up -d

Option 2: Just Docker Compose

If you don't want to clone the whole repo and build from source, you can write a docker-compose.yml that pulls a pre-built image. Check the Moltbot GitHub repo for the latest recommended compose file -- the image names and versions change as the project evolves.

The general structure looks like this:

version: "3.8"
services:
  moltbot:
    image: moltbot/moltbot:latest
    ports:
      - "127.0.0.1:18789:18789"
    volumes:
      - moltbot-data:/root/.moltbot
    restart: unless-stopped

volumes:
  moltbot-data:

Notice the port binding: 127.0.0.1:18789:18789. The 127.0.0.1 part is important. It binds the port to loopback only, not to all interfaces. If you just wrote 18789:18789, Docker would expose the dashboard to your entire network. Don't do that unless you know what you're doing.

The Sandbox: Why Docker Is Great for Moltbot

Here's the real reason a lot of people use Docker with Moltbot.

Moltbot agents can execute commands on your system. That's the whole point -- they interact with your files, run scripts, do things. But "doing things" on your actual machine can be risky. What if an agent runs rm -rf /? What if it installs malware? What if it just does something dumb that breaks your setup?

Docker gives you isolation. Agents run inside containers. If they mess up, they mess up the container. Your host machine is fine. Blow away the container, start fresh.

Configuring Sandbox Mode

The key setting is agents.defaults.sandbox.mode. Set it to "non-main" in your Moltbot config:

agents:
  defaults:
    sandbox:
      mode: "non-main"

What does "non-main" mean? It means all agent tasks run in their own sandbox container rather than the main Moltbot container. Each task gets a fresh, isolated environment. The main Moltbot process stays clean.

This is huge for safety. An agent can go wild inside its sandbox and the worst that happens is you lose that one container. Your actual system, your data, your other running tasks -- all untouched.

There are other sandbox modes too, but "non-main" is the one I'd recommend starting with. It's the right balance of safety and usability.

Docker Compose Commands You'll Use

Starting Moltbot:

docker compose up -d

Stopping:

docker compose down

Viewing logs:

docker compose logs -f

The -f flag follows the logs in real-time. Hit Ctrl+C to stop watching. The logs keep accumulating regardless.

Restarting:

docker compose restart

Running the onboarding again (if you need to reconfigure):

docker compose run onboard

Rebuilding after an update:

docker compose build
docker compose up -d

Updating Moltbot in Docker

If you built from source:

cd moltbot
git pull
docker compose build
docker compose up -d

If you're using a pre-built image:

docker compose pull
docker compose up -d

Easy. No worrying about Node.js versions, no global npm packages, no PATH issues. Just pull and restart.

Persistent Data

By default, Docker containers are ephemeral. When you remove a container, its data is gone. That's bad for Moltbot because you don't want to lose your config and conversation history every time you update.

The compose file should include a volume for Moltbot's data directory (~/.moltbot/ inside the container). Check that your compose file has something like:

volumes:
  - moltbot-data:/root/.moltbot

This stores your data in a Docker volume that survives container removal. You can also bind-mount a host directory instead:

volumes:
  - ./moltbot-data:/root/.moltbot

This puts the data in a moltbot-data/ folder on your host. Easier to back up and inspect. I prefer this approach because I like being able to see and edit config files directly.

Running on a VPS with Docker

Docker is actually an excellent choice for VPS deployments. You get isolation, easy updates, and you don't need to worry about conflicting system packages.

Minimum VPS specs: 1 vCPU, 1GB RAM. Docker adds a tiny bit of overhead but nothing meaningful on modern kernels.

For a VPS setup:

1. Create a dedicated user:

adduser clawd && usermod -aG sudo clawd && su - clawd

2. Install Docker (follow Docker's official docs for your Linux distro)

3. Clone and set up Moltbot:

git clone https://github.com/moltbot/moltbot.git
cd moltbot
docker build -t moltbot .
docker compose run onboard
docker compose up -d

4. Access the dashboard via SSH tunnel:

# From your local machine
ssh -L 18789:127.0.0.1:18789 clawd@your-vps-ip

Then open http://127.0.0.1:18789/ locally. The traffic is encrypted through SSH.

Or use Tailscale for a more permanent solution. Install Tailscale on both your VPS and your local machine, and you can access the dashboard directly over the Tailscale network. No port forwarding, no SSH tunnels, no firewall rules. I'm a big fan.

Never expose port 18789 directly to the internet. The gateway is designed to listen on loopback. If you bypass that, you're inviting trouble.

Docker + moltbot doctor

You can still run moltbot doctor inside the container:

docker compose exec moltbot moltbot doctor

Same diagnostic output, same checks. Works just like the native version.

Resource Limits

If you're on a shared VPS or just want to prevent Moltbot from eating all your RAM, Docker makes it easy to set limits:

services:
  moltbot:
    # ... other config
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: "1.0"

This caps the container at 1GB RAM and 1 CPU core. Adjust based on your needs and available resources.

Common Docker Issues

"Cannot connect to the Docker daemon"

Docker isn't running. Start it:

• Mac/Windows: Open Docker Desktop
• Linux: sudo systemctl start docker

Port already in use

Something else is on port 18789. Find out what:

# Mac/Linux
lsof -i :18789

# Or inside Docker
docker ps

Kill the conflicting process or change Moltbot's port in the compose file.

Build fails with network errors

Docker can't reach the internet. Check your DNS settings, proxy config, or corporate firewall. This one is environment-specific and honestly kinda annoying to debug. Sorry.

Container keeps restarting

Check the logs:

docker compose logs moltbot

Usually it's a config error or missing API key. The onboarding wizard might not have completed successfully. Try running docker compose run onboard again.

Sandbox containers pile up

If you're using the sandbox mode, finished task containers might accumulate. Moltbot should clean these up automatically, but if they pile up:

docker container prune

This removes all stopped containers. Be careful if you have other Docker projects with stopped containers you want to keep.

Everything else

docker compose exec moltbot moltbot doctor

Same old song. moltbot doctor knows what to look for.

Should You Use Docker or Native Install?

Honestly, both work fine. Here's my take:

Use Docker if:

• You want agent sandboxing (the killer feature)
• You're deploying to a VPS
• You don't want to deal with Node.js version management
• You like containers and this is how you roll

Use native install if:

• You want the simplest possible setup
• You're just trying Moltbot out
• You don't have Docker installed and don't want to
• You want agents to have direct access to your host system

There's no wrong answer. I run Docker on my VPS and native on my laptop. Different tools for different situations.

Go set it up.