# Docker

This guide shows you how to run Kameleo inside a Docker container and expose the Local API on your host. Use the containerized deployment when you need an isolated, reproducible environment — for example, in CI pipelines, ephemeral workers, or remote hosts.

The kameleo/kameleo-app:latest image is a multi-platform manifest covering both Windows (Server Core LTSC 2022) and Linux (Ubuntu 22.04). Docker automatically pulls the variant that matches your host OS, no separate tags are needed.

flowchart LR
  classDef cloud fill:#eef6ff,stroke:#88a,stroke-dasharray:5 5;

  SERVICES["Kameleo Cloud Services"]:::cloud
  SCRIPT["Your automation scripts"]
  BROWSER["Your browser"]

  SERVICES <--> CLI

  subgraph CONTAINER["Docker container"]
    direction LR
    GUI["Web UI"]
    CLI["Local CLI instance"]

    subgraph P1["Chroma instance"]
      direction TB
      CHROME(("Profile #1 data"))
    end

    subgraph P2["Junglefox instance"]
      direction TB
      FIREFOX(("Profile #2 data"))
    end

    GUI --> CLI
    CLI --> P1
    CLI --> P2
  end

  BROWSER <--> GUI
  SCRIPT <--> CLI

Kameleo runs under a non-administrative user inside the image. This improves isolation and reduces the surface for privilege escalation.

Mount the data directory as a named Docker volume to persist state (profiles, kernels) across container recreations.

You can configure Kameleo inside the container using the same precedence described in Configure. In container workflows you typically rely on environment variables or command-line flags appended to docker run.

Accepted environment variable names mirror the Engine keys with uppercase; see the full list and defaults in Configuration options.

Mandatory credential must always be provided; without it the app will not authenticate and container startup will fail.

Expose port 5050, pass the PAT, and mount the named volume for persistent data:

docker run --platform linux/amd64 \
    --shm-size=2g \
    -p 5050:5050 \
    -e PAT="your-pat" \
    -v kameleo-data:/data \
    kameleo/kameleo-app:latest

docker pull kameleo/kameleo-app:latest
docker run --name kameleo-app -p 5050:5050 -e PAT="your-pat" -v kameleo-data:C:\data kameleo/kameleo-app:latest

Open in a browser on the host and expect the Swagger UI to load:

http://localhost:5050/swagger

The container exposes the same Local API as the desktop app. Follow the Quickstart guide to install an SDK, create a client pointed at http://localhost:5050, and start your first automated profile.

Use docker-compose.yml for repeatable infrastructure or CI pipelines:

services:
    kameleo-app:
        image: "kameleo/kameleo-app:latest"
        platform: linux/amd64
        ports:
            - "5050:5050"
        environment:
            PAT: your-pat
        volumes:
            - "kameleo-data:/data"
        shm_size: 2g
        restart: unless-stopped
volumes:
    kameleo-data:

services:
    kameleo-app:
        image: "kameleo/kameleo-app:latest"
        ports:
            - "5050:5050"
        environment:
            PAT: your-pat
        volumes:
            - 'kameleo-data:C:\data'
        restart: unless-stopped
volumes:
    kameleo-data:

The published image already defines a HEALTHCHECK that periodically queries the /general/healthcheck endpoint and marks the container as healthy once Kameleo is responsive. Nothing extra is required; the health status is visible via the State column:

docker ps

If you build a custom derivative image (e.g., adding tools) and replace the base CMD, ensure you keep or re-add a healthcheck so orchestrators wait for readiness.

The Linux container includes the Kameleo GUI, a browser-based interface served on port 80. Expose that port to open it on your host:

docker run --platform linux/amd64 \
    --shm-size=2g \
    -p 5050:5050 \
    -p 80:80 \
    -e PAT="your-pat" \
    -v kameleo-data:/data \
    kameleo/kameleo-app:latest

Then open the GUI in your browser:

http://localhost:80

The Kameleo GUI in the Linux container ships a built-in browser-based VNC viewer that lets you watch or interact with the virtual display where browsers run. It is accessible in any modern browser — no additional software is required.

The VNC server is disabled by default to keep resource utilization low. The VNC server starts automatically when opened from the GUI, or you can make it start by setting the VNCENABLE and VNCPASSWORD environment variables. This is necessary if you prefer a native VNC client (for example, RealVNC Viewer or TigerVNC), and you also need to expose port 5900 that carries the raw RFB protocol:

docker run --platform linux/amd64 \
    --shm-size=2g \
    -p 5050:5050 \
    -p 5900:5900 \
    -e PAT="your-pat" \
    -e VNCENABLE="1" \
    -e VNCPASSWORD="your-vnc-password" \
    -v kameleo-data:/data \
    kameleo/kameleo-app:latest

Kameleo Docker containers are compatible with AWS ECS (Elastic Container Service). The supported capacity provider depends on the platform:

When deploying to AWS ECS:

• For Windows, use EC2 capacity providers with Windows Server 2022-compatible instances.
• For Linux, EC2 and Fargate both work; Fargate is recommended for simpler infrastructure management.
• Configure appropriate instance types with sufficient resources for your Kameleo workload.
• Mount persistent storage using named volumes to preserve profile data across container restarts.

By default Kameleo uses software rendering inside the Linux container. If you mount the host GPU into the container, Kameleo automatically detects it and enables hardware-accelerated rendering in the browser. This can improve performance on GPU-intensive pages such as WebGL or canvas-heavy sites.

Pass the DRI device directory and add the host device group IDs so the container user can access them:

docker run --platform linux/amd64 \
    --shm-size=2g \
    --device /dev/dri \
    --group-add $(stat -c '%g' /dev/dri/card0) \
    --group-add $(stat -c '%g' /dev/dri/renderD128) \
    -p 5050:5050 \
    -e PAT="your-pat" \
    -v kameleo-data:/data \
    kameleo/kameleo-app:latest

Install the NVIDIA Container Toolkit on the host, then pass --gpus all:

docker run --platform linux/amd64 \
    --shm-size=2g \
    --gpus all \
    -p 5050:5050 \
    -e PAT="your-pat" \
    -v kameleo-data:/data \
    kameleo/kameleo-app:latest

Check the container logs first:

docker logs <container-name>

Authentication error (PAT_INVALID, exit code 111): the PAT is wrong or expired. Verify the PAT environment variable.

Permission denied on /data (Access to the path '/data/...' is denied): you are using a host bind mount instead of a named volume. Replace -v ~/kameleo-data:/data with -v kameleo-data:/data. The container runs as a non-root user and cannot write to a host directory owned by a different user.

Manually query the health endpoint to confirm whether the Engine started successfully:

curl http://localhost:5050/general/healthcheck

If the request times out, the container may still be starting up. Kernel downloads run on first launch and can take several minutes depending on your connection.

If browsers fail to open or crash immediately, the container is likely missing the --shm-size=2g flag. The default shared memory size of 64 MB is insufficient for browsers. Restart the container with --shm-size=2g.

Kernel downloads are rate limited. If you start many containers simultaneously without a mounted volume, each container downloads its own copy of all kernels and can exhaust the allowed download rate. Always mount the data directory so kernels are downloaded once and reused.