Install with Docker

This guide sets up Comis in a Docker container. You do not need Node.js installed on your system — Docker handles everything.

You don’t need to understand the technical details to use this feature. The configuration examples below are copy-paste ready.

You need Docker Engine 24+ and Docker Compose v2+ installed. Check with:

docker --version
docker compose version

Production = Linux host only. macOS and Windows Docker Desktop run containers inside a linuxkit VM whose kernel does not allow nested PID-namespace + procfs mounts. This breaks the bubblewrap exec sandbox.On Docker Desktop the daemon detects this at startup and automatically disables the exec sandbox so the agent is functional for development. The trade-off:

✅ Dev/testing UX on Mac and Windows: the agent runs end-to-end. You can drive exec commands, run scripts in the workspace, and exercise every feature that depends on shell execution.
❌ The documented exec-isolation boundary is absent on Docker Desktop. With the sandbox off, agent-issued shell commands may read /home/comis/.comis/.env, the encrypted secrets.db, /etc/comis/config.yaml, channel tokens, the SECRETS_MASTER_KEY, and anything else the daemon user owns. Treat prompt-driven shell execution as host-equivalent authority within the container account.

This is fine for development and local testing only. For production, deploy to a real Linux host (bare metal, VPS, or a Linux cloud VM) and verify that bubblewrap is active after startup. Some Linux hosts restrict unprivileged user namespaces through AppArmor and require the host configuration described in Operations: Docker → Per-command exec sandbox.See Operations: Docker → Platform Support for the full explanation, including local Linux-VM alternatives (Lima / Colima vz driver / OrbStack / UTM) that get you a working sandbox on a Mac.

Automated setup

The repository includes a setup script that creates directories, generates a gateway token, builds the Docker image, and starts the daemon. This is the recommended way to get started.

Clone the repository

git clone https://github.com/comisai/comis.git
cd comis

Configure Compose and credentials

Copy the included Compose settings template:

cp .env.docker.example .env

Keep persistent credentials in the mounted daemon environment file (the default COMIS_ENV_FILE is ~/.comis/.env):

mkdir -p ~/.comis
chmod 700 ~/.comis
touch ~/.comis/.env
chmod 600 ~/.comis/.env
${EDITOR:-vi} ~/.comis/.env

Add the credentials required by your chosen provider, for example ANTHROPIC_API_KEY=... or OPENAI_API_KEY=.... OAuth and local keyless providers do not need a static provider key. If you change COMIS_ENV_FILE in the project-root .env, edit that target instead.

Never store API keys, tokens, or passwords directly in config.yaml. Use the .env file or Secret Manager for credential management.

.env.docker.example contains image, path, and network settings plus a small set of optional explicit credential overrides. Blank overrides are removed by the container entrypoint, so they cannot hide non-empty values from COMIS_ENV_FILE.

Run the setup script

./docker-setup.sh

The script performs these steps automatically:

Creates the data and config directories (both ~/.comis by default)
Generates a gateway authentication token (or reuses an existing one)
Writes token and network settings to COMIS_ENV_FILE
Creates a schema-valid config.yaml with authenticated gateway, logging, and memory paths
Builds the Docker image from the included Dockerfile
Prepares data and config ownership for the container’s non-root user (UID 1000)
Starts the comis-daemon service and waits for its health check to pass

The script prints the gateway URL and credential-file path only after the daemon is healthy; it does not echo the token. On timeout it exits nonzero and prints the logs command to run.

Verify

Confirm the daemon is healthy:

curl http://localhost:4766/health

Expected response:

{ "status": "ok" }

Browser tool (optional)

The published image is browser-free. To use the agent browser tool, rebuild from the repo with one of three build args mirroring the bare-VPS install flags. Image-size impact in parentheses.

# Stock Chrome (+400 MB)
docker build \
  --build-arg COMIS_WITH_BROWSER=1 \
  -t comisai/comis:browser .

# Headed via Xvfb — for workflows that require a display server (+15 MB on top)
docker build \
  --build-arg COMIS_WITH_XVFB=1 \
  -t comisai/comis:xvfb .

# Optional CloakBrowser runtime (+500 MB)
docker build \
  --build-arg COMIS_WITH_CLOAKBROWSER=1 \
  -t comisai/comis:cloak .

# Full stack
docker build \
  --build-arg COMIS_WITH_CLOAKBROWSER=1 \
  --build-arg COMIS_WITH_XVFB=1 \
  -t comisai/comis:cloak-xvfb .

The entrypoint shim (/usr/local/bin/comis-entrypoint.sh) starts Xvfb on :99 automatically when the image was built with COMIS_WITH_XVFB=1. It verifies the X11 socket before starting the daemon and exits if the virtual display cannot start. The daemon’s findChrome() probes ~/.cloakbrowser/chromium-*/chrome first, so when the cloak binary is baked in it wins over stock Chrome with no config change. Run the CloakBrowser image identically to the no-browser one — same volumes, same ports, same environment variables:

docker run -d \
  --name comis \
  --restart unless-stopped \
  -p 127.0.0.1:4766:4766 \
  -v comis-data:/home/comis/.comis \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  comisai/comis:cloak

Alternative: installer-based image

The repo also ships Dockerfile.install. It packs the local workspace and runs the installer’s non-interactive, non-root package-install path inside Ubuntu 24.04. This exercises package installation and selected browser-provisioning branches, but skips interactive setup, initialization, service management, dedicated-user creation, and the public-registry download path.

docker build -f Dockerfile.install \
  --build-arg COMIS_WITH_CLOAKBROWSER=1 \
  -t comis-installed:cloak .

The main Dockerfile is the primary multi-stage image path. Dockerfile.install is a focused installer validation image, not a parity image for a managed host.

CloakBrowser does not include a proxy, change IP reputation, or guarantee access to any site. Review the target site’s terms and the binary license before enabling it.

See agent-tools/browser for the browser-tool security model.

Optional services

The daemon is the only service that starts by default. The web dashboard and CLI are available as Docker Compose profiles.

Web dashboard

Start the Nginx-served web UI on port 8080:

docker compose --profile web up -d

Then open http://localhost:8080 in your browser. The dashboard proxies API calls and WebSocket connections to the daemon automatically.

CLI

Run one-shot CLI commands against the running daemon:

docker compose --profile cli run --rm comis-cli status

The CLI container shares the daemon’s network namespace, so it reaches the gateway at 127.0.0.1:4766 without extra configuration.

Stopping and updating

Action	Command
Stop daemon	`docker compose down`
Stop web dashboard	`docker compose --profile web down`
Restart daemon	`docker compose restart comis-daemon`
Update	`git pull && docker compose up -d --build`
View logs	`docker compose logs -f comis-daemon`

Deploying on a VPS

The supplied Compose file and quick-start examples bind the host port to 127.0.0.1 by default. If you omit the host address (-p 4766:4766) or set the host-side bind to 0.0.0.0, a VPS may expose the gateway to the public internet. Choose an intentional posture below before changing the loopback default.

The wizard’s “LAN mode” sets gateway.host: 0.0.0.0 inside the container. That’s correct — the daemon must bind all interfaces so Docker port-forwarding can reach it. The exposure decision is made on the host side by the -p mapping (or Compose ports:). Confusing the two is the #1 way to accidentally expose a daemon publicly.

Recommended: loopback bind + reverse proxy

Bind the host port to loopback only and put nginx (or Caddy/Traefik) in front to terminate TLS:

docker run -d \
  --name comis \
  --restart unless-stopped \
  -p 127.0.0.1:4766:4766 \
  -v comis-data:/home/comis/.comis \
  -e COMIS_CONFIG_PATHS=/home/comis/.comis/config.yaml \
  comisai/comis:latest-slim

Or in docker-compose.yml:

ports:
  - "127.0.0.1:4766:4766"

Then point your reverse proxy at http://127.0.0.1:4766 (HTTP) and http://127.0.0.1:4766/ws (WebSocket). See Operations: Reverse Proxy for full nginx / Caddy snippets with WebSocket upgrade headers.

Acceptable: direct exposure + token auth + firewall

If you don’t want a reverse proxy, you can expose the gateway directly, but you must combine three controls:

Token auth on the gateway. The init wizard enables this by default (Authentication method → Token). Verify your ~/.comis/config.yaml contains a gateway.tokens: section and ~/.comis/.env has a COMIS_GATEWAY_TOKEN.

Firewall to trusted IPs only. On Ubuntu/Debian:

sudo ufw allow from <your-trusted-ip> to any port 4766
sudo ufw enable

TLS. Without TLS, the bearer token crosses the wire in cleartext. Either run with gateway.tls.cert configured (see HTTP gateway: mTLS or front it with a reverse proxy that does TLS for you (in which case use the recommended posture above instead).

`comis status` from your laptop against a remote VPS

The CLI’s comis status defaults to reading ~/.comis/config.yaml on the machine where it runs. Copying the VPS’s config to your laptop won’t work on its own — gateway.host: 0.0.0.0 is a bind address that the CLI remaps to local loopback, not the VPS’s public IP. Set COMIS_GATEWAY_URL (and the matching token) on your laptop instead:

export COMIS_GATEWAY_URL=wss://comis.example.com/ws
export COMIS_GATEWAY_TOKEN=<the-token-from-the-VPS>
comis status

Use wss:// (TLS) when the gateway is reachable over the public internet. Use ws:// only over a trusted network (VPN, SSH tunnel).

Common issues

Setup script fails

Common causes:

Docker not running — start Docker Desktop or the Docker daemon
Port 4766 in use — stop the other process or set COMIS_GATEWAY_PORT in .env
Missing openssl — the script uses openssl rand -hex 32 for token generation; install it with your system package manager

Cannot access dashboard from host

Symptom: curl http://127.0.0.1:4766/health returns “connection refused” or “connection reset by peer” even though the container is reported healthy.Fix: Two distinct binds are involved — get them in the right place:

Host-side bind (which interface the host listens on): controlled by COMIS_GATEWAY_HOST in the project-root Compose .env. The default is 127.0.0.1; use 0.0.0.0 only when you intentionally want LAN exposure and have configured authentication and transport security.
Container-side bind (which interface the daemon listens on inside the container): the base Compose file sets this to 0.0.0.0 so port forwarding can reach the daemon. A mounted config.yaml has higher precedence; if it sets gateway.host: 127.0.0.1, change it to 0.0.0.0 or remove the field.

Other things to check:

The container is running and healthy: docker compose ps
No firewall is blocking the port
Confirm no additional Compose file intentionally replaces the loopback host-port mapping.

Container exits immediately

Symptom: The container starts but stops within seconds.Fix: Check the logs for the error:

docker compose logs comis-daemon

Common causes:

Invalid config.yaml — check YAML syntax and required fields. The daemon writes a recovery snapshot at ~/.comis/config.last-good.yaml; run cp ~/.comis/config.last-good.yaml ~/.comis/config.yaml to restore the previous-known-good config, then docker compose restart.
Missing API key — verify COMIS_ENV_FILE (default ~/.comis/.env) has the correct variable name
Port already in use — another process is using port 4766 on the host

Daemon can't write to .env (`Is a directory` error)

Symptom: Bringing up Compose without first running docker-setup.sh, the daemon fails to persist credentials and you see cannot create /home/comis/.comis/.env: Is a directory in the logs.Cause: Docker bind-mounts ${COMIS_ENV_FILE:-~/.comis/.env} into the container. If the host path doesn’t exist, Docker silently creates it as a directory instead of a file, then every write fails.Fix: create the file before docker compose up:

mkdir -p ~/.comis
touch ~/.comis/.env
chmod 600 ~/.comis/.env

If .env already exists as a directory, remove it first: rmdir ~/.comis/.env && touch ~/.comis/.env.The repo’s docker-setup.sh handles this automatically — this only affects manual docker compose up.

Next steps

Configuration Guide

Customize your agent settings, add channels, and configure advanced options.

Verify Installation

Run diagnostic commands to confirm everything is working.

Operations: Docker

Docker deployment boundaries, multi-stage builds, and security hardening.

​Automated setup

​Browser tool (optional)

​Alternative: installer-based image

​Optional services

​Web dashboard

​CLI

​Stopping and updating

​Deploying on a VPS

​Recommended: loopback bind + reverse proxy

​Acceptable: direct exposure + token auth + firewall

​comis status from your laptop against a remote VPS

​Common issues

​Next steps

Configuration Guide

Verify Installation

Operations: Docker

Automated setup

Browser tool (optional)

Alternative: installer-based image

Optional services

Web dashboard

CLI

Stopping and updating

Deploying on a VPS

Recommended: loopback bind + reverse proxy

Acceptable: direct exposure + token auth + firewall

`comis status` from your laptop against a remote VPS

Common issues

Next steps