LumaBrowser Docker Deployment

LumaBrowser Docker packages the full browser automation platform into a self-hosted container. It runs a lightweight Linux desktop with LumaBrowser, exposing the REST API, MCP tools, and a web-based visual desktop via your browser.

The Docker image is the same free, open source LumaBrowser as the desktop app. It needs no license key, no activation, and no network check on startup. The Dockerfile and compose files are in the LumaBrowser repository. Organizations that modify LumaBrowser and want to keep their changes private can get a commercial license; it unlocks nothing.

• Docker 20.10+ with Docker Compose v2
• The LumaBrowser source, cloned from GitHub (the compose files build the image from it)
• 2 GB+ RAM allocated to the container (Chromium requires adequate shared memory)
• No GPU needed: GPU acceleration is not used in the container

1. Get the source and create a .env file

git clone https://github.com/amurgola/LumaBrowser.git
cd LumaBrowser
echo "LUMA_VNC_PASSWORD=your-secure-password" > .env

2. Run with Docker Compose

docker compose up -d

3. Access LumaBrowser

4. Verify

# Check the API is responding
curl http://localhost:3000/api/health

# List available MCP tools
curl http://localhost:3000/api/mcp/tools

# View container logs
docker compose logs lumabrowser

Required

Optional

Configure LLM providers via environment variables so AI features (AI Chat, agents, Timed Tasks, selector fallback) work immediately on startup.

OpenAI-Compatible (LM Studio, Ollama, vLLM)

Anthropic (Claude)

Example: LM Studio on Host Machine

# .env file
LUMA_VNC_PASSWORD=secret123
LUMA_LLM_PROVIDER=openai
LUMA_OPENAI_ENDPOINT=http://host.docker.internal:1234
LUMA_OPENAI_KEY=lm-studio
LUMA_OPENAI_MODEL=qwen2.5-7b-instruct

Use host.docker.internal to reach services running on the Docker host machine (e.g., LM Studio, Ollama).

LumaBrowser stores settings, network watchers, and the rest of its app data in a SQLite database at /data/settings.db. Mount a volume to persist data across container restarts.

volumes:
  - luma-data:/data

Shared Volumes (Multi-Instance)

Multiple containers can share the same data volume. SQLite WAL mode supports concurrent readers, and a 5-second busy timeout handles write contention gracefully.

Note: For deployments with heavy write workloads, use separate volumes per instance to avoid contention.

No prebuilt image is published. The compose file builds the image from the cloned repository the first time you run it.

git clone https://github.com/amurgola/LumaBrowser.git
cd LumaBrowser
LUMA_VNC_PASSWORD=change-me docker compose up -d

To pick up a newer version, git pull and run docker compose up -d --build.

See Docker Compose Reference for the full configuration file.

Run as many LumaBrowser instances as you need; there is no seat or machine limit. Use offset ports to avoid conflicts.

# docker-compose.multi.yml
services:
  lumabrowser-1:
    build: { context: ., dockerfile: docker/Dockerfile }
    environment:
      - LUMA_VNC_PASSWORD=${LUMA_VNC_PASSWORD}
    ports:
      - "3001:3000"
      - "6081:6080"
    volumes:
      - shared-data:/data
    shm_size: '2gb'

  lumabrowser-2:
    build: { context: ., dockerfile: docker/Dockerfile }
    environment:
      - LUMA_VNC_PASSWORD=${LUMA_VNC_PASSWORD}
    ports:
      - "3002:3000"
      - "6082:6080"
    volumes:
      - shared-data:/data
    shm_size: '2gb'

volumes:
  shared-data:

docker compose -f docker-compose.multi.yml up -d

# docker-compose.yml
services:
  lumabrowser:
    build:
      context: .
      dockerfile: docker/Dockerfile
    environment:
      # Required
      - LUMA_VNC_PASSWORD=${LUMA_VNC_PASSWORD}
      # Ports
      - LUMA_API_PORT=${LUMA_API_PORT:-3000}
      - LUMA_VNC_PORT=${LUMA_VNC_PORT:-6080}
      - LUMA_DATA_DIR=/data
      # LLM Configuration (optional)
      - LUMA_LLM_PROVIDER=${LUMA_LLM_PROVIDER:-}
      - LUMA_OPENAI_ENDPOINT=${LUMA_OPENAI_ENDPOINT:-}
      - LUMA_OPENAI_KEY=${LUMA_OPENAI_KEY:-}
      - LUMA_OPENAI_MODEL=${LUMA_OPENAI_MODEL:-}
      - LUMA_ANTHROPIC_KEY=${LUMA_ANTHROPIC_KEY:-}
      - LUMA_ANTHROPIC_MODEL=${LUMA_ANTHROPIC_MODEL:-}
      - LUMA_ANTHROPIC_ENDPOINT=${LUMA_ANTHROPIC_ENDPOINT:-}
    ports:
      - "${LUMA_API_PORT:-3000}:3000"
      - "${LUMA_VNC_PORT:-6080}:6080"
    volumes:
      - luma-data:/data
    shm_size: '2gb'
    restart: unless-stopped

volumes:
  luma-data:

The container runs five managed processes via supervisord:

Startup Sequence

1. Entrypoint checks that LUMA_VNC_PASSWORD is set
2. Pre-seeds LLM config into the SQLite database, if LLM variables are set
3. Starts all processes via supervisord
4. LumaBrowser opens on the virtual display with REST API on port 3000

API Endpoints

All LumaBrowser REST API endpoints are available inside the container. Key routes:

• Non-root user: LumaBrowser runs as the luma user inside the container, not root.
• VNC password required: The container refuses to start without a LUMA_VNC_PASSWORD.
• Internal VNC port: Port 5900 is only accessible inside the container. External access goes through noVNC on port 6080.
• API access: In Docker the REST API accepts connections from any address and needs no key by default. Do not publish port 3000 to a network you do not trust without setting an API key in Settings.
• Shared memory: shm_size: 2gb is required. Chromium uses /dev/shm for rendering; the Docker default of 64MB causes crashes.

Production Recommendations

• Place an HTTPS reverse proxy (nginx, Caddy, Traefik) in front of the noVNC port for encrypted desktop access.
• Use Docker secrets or a .env file (gitignored) instead of passing credentials on the command line.
• Restrict network access so only trusted clients can reach ports 3000 and 6080.

Container exits immediately

Check docker compose logs lumabrowser. The most common cause:

• LUMA_VNC_PASSWORD not set. The entrypoint refuses to start without it.

noVNC shows a black screen

• Wait 10-15 seconds for LumaBrowser to fully initialize
• Check that shm_size is at least 2gb in your compose file
• Verify Xvfb is running: docker compose exec lumabrowser ps aux | grep Xvfb

REST API not responding

• Verify the container is healthy: docker compose ps should show (healthy)
• Check LumaBrowser started: docker compose logs lumabrowser | grep "HTTP server listening"
• Ensure port 3000 is mapped: docker compose port lumabrowser 3000

LLM features not working

• Verify LLM env vars are set (LUMA_LLM_PROVIDER, endpoint, key, model)
• For local LLM servers, use host.docker.internal instead of localhost
• Check the LLM server is accessible from inside the container: docker compose exec lumabrowser curl http://host.docker.internal:1234/v1/models

D-Bus errors in logs

Messages like Failed to connect to the bus are cosmetic warnings. There is no system bus inside the container, but this does not affect LumaBrowser functionality.