Docker

Running Comis in Docker, including Linux production boundaries

Docker packages Comis and all its dependencies into a single container, making deployment consistent across any server. This page covers the production setup — for a quick start, see the Installation Docker page.

The Installation Docker page covers basic container setup using the docker-setup.sh script. This page focuses on production hardening: multi-stage builds, health checks, security, volume management, and the full service architecture.

Production Dockerfile

The repository includes a 4-stage Dockerfile that separates application compilation from the runtime image. Comis TypeScript source and development dependencies are removed after compilation; runtime language toolchains and agent utilities are installed deliberately in the final stage.

Build architecture

Stage 1 — build: Starts from node:22-bookworm with corepack/pnpm enabled. Copies dependency manifests first for layer caching, installs dependencies with a BuildKit cache mount on the pnpm store, compiles all packages with pnpm build, then prunes devDependencies and removes .d.ts, .map, and .tsbuildinfo files.

Stage 2 — runtime-assets: Copies the built output from Stage 1 and strips remaining source files (src/, test/, tsconfig*.json, vitest.config.*) so only dist/ and node_modules remain.

Stage 3 — base variant selection: Two base image options are defined:

• base-default — full node:22-bookworm Debian base
• base-slim — smaller node:22-bookworm-slim Debian base

The COMIS_VARIANT build arg selects which base to use (default: slim).

Stage 4 — final: Installs the system, media, sandbox, and language tools used at runtime (including Git, Python/pipx, ffmpeg, bubblewrap, Go, DuckDB, uv, and Rust), creates a non-root comis user (UID/GID 1000), copies the compiled application, and creates the comis CLI symlink. dumb-init runs as PID 1. Port 4766 has a health check with a 60s interval, 10s timeout, 30s start period, and 3 retries.

Build args

ARG COMIS_NODE_BOOKWORM_IMAGE="node:22-bookworm"
ARG COMIS_NODE_BOOKWORM_SLIM_IMAGE="node:22-bookworm-slim"
ARG COMIS_VARIANT="slim"
ARG COMIS_DOCKER_APT_PACKAGES=""
ARG COMIS_WITH_BROWSER=0
ARG COMIS_WITH_XVFB=0
ARG COMIS_WITH_CLOAKBROWSER=0

• Digest pinning — the base image ARGs accept @sha256: digests for reproducible builds. Override at build time with values resolved from docker inspect --format='{{.RepoDigests}}' node:22-bookworm, e.g. docker build --build-arg COMIS_NODE_BOOKWORM_IMAGE=node:22-bookworm@sha256:<digest> ....
• Variant selection — set COMIS_VARIANT=default for the full image with debugging tools, or leave as slim for production.
• Custom packages — set COMIS_DOCKER_APT_PACKAGES to install additional system packages into the final image.
• Browser tool — three independent flags mirror the bare-VPS installer: COMIS_WITH_BROWSER=1 installs Google Chrome + headless shared libs; COMIS_WITH_XVFB=1 adds Xvfb (the entrypoint verifies its :99 socket before starting the daemon and exits if the display fails); COMIS_WITH_CLOAKBROWSER=1 installs CloakBrowser as an alternative Chromium runtime instead of stock Chrome. Runtime limitations and licensing are documented in Browser runtime options.

Installer-built variant (Dockerfile.install)

The repo ships a second Dockerfile that packs the local workspace and invokes install.sh inside Ubuntu rather than copying the main multi-stage build output directly:

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

Use this to exercise the installer’s non-interactive package-install and browser-provisioning branches in CI. It skips interactive setup, initialization, service management, dedicated-user creation, and the public-registry download path, so it is not a parity image for a managed host. The main Dockerfile remains the primary multi-stage image path.

The multi-stage build removes Comis TypeScript source and development dependencies from the final image. The configured runtime tools and language toolchains remain available to agents. The full Dockerfile is in the repository root.

Docker Compose

The docker-compose.yml in the repository root defines three services with a profile-based activation model.

Services

comis-daemon (always runs):

• Gateway port binding via COMIS_GATEWAY_HOST and COMIS_GATEWAY_PORT env vars (default: 127.0.0.1:4766)
• Volumes for /home/comis/.comis (persistent data) and /etc/comis (config); both bind-mount the same host dir (~/.comis by default)
• A mounted COMIS_ENV_FILE for persistent credentials, plus explicit pass-through for a small set of optional non-empty provider/channel overrides
• Health check: curl -sf http://127.0.0.1:4766/health (60s interval, 10s timeout, 30s start period, 3 retries)
• Resource limits: 2G memory / 2 CPU (limit), 256M / 0.5 CPU (reservation)
• JSON log rotation: 50MB max size, 5 files

comis-web (profile: web):

• Nginx-served Lit SPA dashboard on port 8080
• Built from Dockerfile.web (see Web dashboard below)
• Depends on a healthy comis-daemon
• Health check via wget on port 8080

comis-cli (profile: cli):

• Shares the daemon’s network namespace (network_mode: service:comis-daemon) so it reaches the gateway at 127.0.0.1:4766
• Interactive mode (stdin/tty enabled) for one-shot commands
• Security hardened: no-new-privileges, drops NET_RAW and NET_ADMIN capabilities

Using profiles

# Start only the daemon (default)
docker compose up -d

# Start daemon + web dashboard
docker compose --profile web up -d

# Run a CLI command against the running daemon
docker compose --profile cli run --rm comis-cli status
docker compose --profile cli run --rm comis-cli agent list

Build and run

# Build and start (first time or after code changes)
docker compose up -d --build

# Build web dashboard image (if using web profile)
docker compose --profile web build
docker compose --profile web up -d

View logs

docker compose logs -f comis-daemon

Look for the "Comis daemon started" message confirming the daemon is running.

Stop services

# Stop daemon
docker compose down

# Stop web dashboard
docker compose --profile web down

Volume management

The daemon uses two mount points inside the container:

Container path	Purpose	Default host path
/home/comis/.comis	SQLite databases, logs, traces, secrets, .env	~/.comis
/etc/comis	Canonical Linux config path — same host dir as above; the daemon reads config.yaml here and writes config.last-good.yaml next to it	~/.comis

Files in /home/comis/.comis

File	What it contains
memory.db	Agent conversations and memory (SQLite database)
daemon.log	Log files (if file logging is enabled)
secrets.db	Encrypted secrets store
traces/	Execution traces
.env	Runtime environment (token, network settings)

Use an explicit volume or bind mount for /home/comis/.comis. The image declares this path as a volume, so Docker may create an anonymous volume when you omit -v; that state is easy to orphan when replacing the container. The Compose file binds COMIS_DATA_DIR (default ~/.comis) so the location and backup lifecycle are explicit.

Backup

docker compose stop comis-daemon
docker cp comis-daemon:/home/comis/.comis ./comis-backup
docker compose start comis-daemon

Health checks

The HEALTHCHECK directive in the Dockerfile sends a request to the GET /health endpoint. Configuration:

Parameter	Value
Interval	60s
Timeout	10s
Start period	30s
Retries	3

The endpoint returns:

{ "status": "ok", "timestamp": "2026-03-15T10:00:00.000Z" }

Docker uses the health check to determine container status:

Status	What it means
healthy	The daemon is running and the gateway is responding
unhealthy	Three consecutive health checks failed
starting	Within the 30s start period; failures are not counted

You can see the health status in docker ps output:

docker ps

CONTAINER ID   IMAGE        STATUS                   PORTS
abc123         comis:local  Up 5 minutes (healthy)   127.0.0.1:4766->4766/tcp

With restart: unless-stopped in Compose, Docker automatically restarts the container if it exits.

Security

The production setup includes several hardening measures:

• Non-root user — the container runs as the comis user (UID/GID 1000), not as root
• dumb-init — proper PID 1 signal handling prevents zombie processes and ensures clean shutdowns
• Digest-pinned base images — ARGs at the top of the Dockerfile accept @sha256: digests for reproducible, tamper-evident builds
• UID/GID 1000 — predictable file ownership on host-mounted volumes
• Writable state mounts — both /home/comis/.comis (data, including .env) and /etc/comis (config) are mounted read-write so the daemon can persist new credentials (via the agent’s gateway env_set action, comis configure, or the env.set RPC) and write its config.last-good.yaml snapshot next to config.yaml for the bootstrap-failure recovery path. Prompt-injected exec is contained separately by the bwrap sandbox, which excludes /home/comis/.comis and /etc/comis from the per-command mount set entirely (see Per-command exec sandbox below).
• Minimal base image — node:22-bookworm-slim has fewer packages and a smaller attack surface than the full image
• No unnecessary ports — only port 4766 is exposed
• Resource limits — memory and CPU limits prevent runaway processes (2G/2CPU limit, 256M/0.5CPU reservation)
• JSON log rotation — daemon logs rotate at 50MB with 5 files retained, preventing disk exhaustion
• CLI hardening — the CLI service sets security_opt: no-new-privileges and drops NET_RAW and NET_ADMIN capabilities

Platform Support

Production deployments must run on a Linux host — bare metal, a Linux VPS, or any cloud Linux VM. macOS and Windows Docker Desktop are supported for development and testing only.

Why

Docker Desktop runs containers inside a linuxkit VM. Its kernel does not allow a nested PID namespace to mount a fresh procfs — the operation EPERMs even when the container has apparmor=unconfined and seccomp=unconfined. The bubblewrap exec sandbox always uses --unshare-pid paired with --proc /proc, so on Docker Desktop every bwrap invocation aborts at the proc-mount step before forking the inner shell.

To keep the agent functional for local testing despite this kernel limitation, the daemon detects the failure mode at startup (via a one-shot smoke test) and automatically disables the exec sandbox when running inside a container with a non-functional bwrap. Behaviour by environment:

Environment	Sandbox state	exec works?	Trust boundary
Linux host (bare metal, VPS, cloud VM)	bwrap active	yes, sandboxed	per-command bwrap mount-set isolation
Docker Desktop on macOS / Windows	auto-disabled	yes, unsandboxed	the container itself (effectively none, see below)
Bare-metal Linux with broken bwrap (rare)	bwrap returned anyway	no, fails at runtime	n/a — operator must fix kernel/userns config

Inside Docker Desktop with the sandbox auto-disabled, agent-issued shell commands run as the comis user with full read access to everything the daemon owns inside the container — /home/comis/.comis/.env, the encrypted secrets.db, /etc/comis/config.yaml, channel tokens, the SECRETS_MASTER_KEY. A single prompt-injected cat /home/comis/.comis/.env exfiltrates them all. This is why Docker Desktop is dev/testing only. On a real Linux host the sandbox runs unrestricted and these paths are not mounted into the bwrap’d process at all.

You can confirm the active mode in the daemon’s startup logs:

docker compose logs comis-daemon | grep -E "Exec sandbox|smoke test"

Log line	Meaning
Exec sandbox provider detected provider=bwrap	Sandbox is active.
Exec sandbox DISABLED ... shell commands will run UNSANDBOXED	Auto-disabled fallback. Do not use this configuration in production.
bwrap installed but smoke test failed -- exec sandbox is non-functional on this kernel	Bare-metal kernel rejected bwrap. Investigate and fix; do not deploy.

Recommendations for Mac / Windows users

Use case	Recommendation
Local development / quick try-out	Docker Desktop is the fastest path. Sandbox is auto-disabled — treat the container’s data dir as untrusted, never put real production secrets in ~/.comis-docker/.env.
Local development that exercises exec with a real sandbox	Use a Linux VM on your Mac instead of Docker Desktop: Lima, Colima with the vz VM type, OrbStack with a Linux distro, or UTM. The container kernel inside those is a real Linux kernel and bubblewrap runs unrestricted.
Production / multi-user deployment	Deploy to a real Linux host: any major cloud VM, a self-hosted Linux server, or a single-board computer running Linux. The same image and compose files work without changes.

Per-command exec sandbox (bubblewrap)

The Docker image ships bubblewrap (bwrap) and the daemon uses it as a per-command sandbox for every shell command issued by the agent’s exec skill. This is not redundant with Docker’s container isolation — the two boundaries protect different things:

Boundary	What it isolates
Docker	The container from the host kernel and other containers
bwrap	Each agent-issued shell command from the daemon’s own data inside the container — /home/comis/.comis/.env, /home/comis/.comis/secrets.db, /etc/comis/config.yaml, channel tokens, the master encryption key

Why this matters

Comis processes user input (chat messages, channel events) through an LLM that has tool-use authority. A prompt-injection-style payload can drive the exec skill to run arbitrary shell commands. Without bwrap, those commands run as the comis user inside the container — the same user that owns /home/comis/.comis — so a single cat /home/comis/.comis/.env would exfiltrate SECRETS_MASTER_KEY, which decrypts every credential ever stored in secrets.db. That makes the “container is the trust boundary” model unsafe for any deployment that accepts untrusted user input and stores secrets and enables exec.

bwrap closes this gap by running each exec’d command under --unshare-all (new mount/pid/ipc/uts/user namespaces, only network is shared) and only mounting the agent’s workspace, system binaries (read-only), and a fresh tmpfs for /tmp. /home/comis/.comis, /etc/comis, and /home/comis are not mounted into the sandbox — they don’t exist from the perspective of an exec’d command.

Required compose security_opt

docker-compose.yml configures the daemon service with:

security_opt:
  - apparmor=unconfined
  - seccomp=unconfined
  - systempaths=unconfined

These opt-outs are required because bwrap needs to create a user + pid namespace and mount a private /proc inside it, and Docker’s defaults block all three layers:

• AppArmor — the default docker-default AppArmor profile denies unprivileged user-namespace creation by binaries inside the container. Without apparmor=unconfined, bwrap fails with setting up uid map: Permission denied.
• seccomp — Docker’s default seccomp profile filters several unshare and clone flags that bwrap needs. Without seccomp=unconfined, the same userns setup is blocked at the syscall layer instead of AppArmor.
• systempaths — Docker masks and read-only-binds parts of /proc by default, which makes bwrap’s --proc /proc mount in the new namespace fail with Can't mount proc on /newroot/proc: Operation not permitted. Without systempaths=unconfined, userns succeeds but the sandbox aborts at the proc-mount step.

Ubuntu 23.10+ / 24.04 hosts need a host-level change too. These hosts set kernel.apparmor_restrict_unprivileged_userns=1, which denies user namespaces to the now-unconfined container bwrap — so even with all three security_opt entries, bwrap fails at setting up uid map: Permission denied. On such hosts also run, on the host:

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0   # persist in /etc/sysctl.d

(Alternatively, load an AppArmor profile that grants userns to /usr/bin/bwrap.) This is a host setting; docker-compose.yml cannot set it.

When bwrap fails, the daemon does not abort — it logs a WARN and runs agent-issued shell commands unsandboxed. Always check the startup logs for Exec sandbox provider detected (provider name bwrap) to confirm the sandbox is active — if you see the sandbox disabled, the broker’s network containment is not enforced.

Verifying the sandbox

After docker compose up -d, confirm bwrap is active:

# Should print "bwrap"
docker compose logs comis-daemon | grep "Exec sandbox provider detected"

# Should print "/usr/bin/bwrap"
docker compose exec comis-daemon which bwrap

# Should fail with "Permission denied" or "No such file or directory"
# (bwrap's mount set excludes /home/comis/.comis)
docker compose exec comis-daemon bwrap \
  --unshare-all --share-net \
  --ro-bind /usr /usr --ro-bind /lib /lib --ro-bind /lib64 /lib64 \
  --ro-bind /bin /bin --ro-bind /etc/passwd /etc/passwd \
  --tmpfs /tmp \
  /bin/sh -c 'cat /home/comis/.comis/.env'

Secrets management

Comis supports three credential-storage modes, selected via security.storage in config.yaml. The encrypted secrets.db is the default — the master key is auto-generated on first boot and written to ~/.comis/.env (mode 0600). To opt out, set security.storage: env (or file).

Mode (security.storage)	When to use	How it works
encrypted (default)	All deployments. The encrypted store is active immediately on first boot — no manual key generation required.	On first boot with no SECRETS_MASTER_KEY present, the daemon auto-generates a 32-byte master key, writes it to <data dir>/.env (mode 0600), and opens secrets.db on the same boot. Back up ~/.comis/.env — losing SECRETS_MASTER_KEY makes secrets.db permanently unreadable (AES-256-GCM, no key escrow). All three credential families — named secrets, OAuth profiles, and MCP OAuth tokens — live in secrets.db (the secrets, oauth_profiles, and mcp_credentials tables); no plaintext mcp-tokens/ directory is written.
env / file (explicit opt-out)	Deployments whose operator deliberately accepts environment-only (env) or plaintext-at-0600 file storage (file).	Set security.storage: env or file in config.yaml; an empty master-key value does not select either mode. env is read-only and does not support MCP OAuth login. file uses the daemon’s 0600 plaintext credential files, including mcp-tokens/.

Important caveat about secrets.db inside Docker

The default Docker layout keeps secrets.db and its master key in the same mounted data directory. Encryption protects the database at rest when the key is separated from a copied database, but it does not protect against a process or account that can read both files. Keep the mount private, verify the exec sandbox is active, and back up secrets.db together with COMIS_ENV_FILE. Do not interpret this limitation as a reason to switch silently to plaintext file storage; that mode is an explicit operator choice.

Adding a credential

# Persistent first-boot source (default COMIS_ENV_FILE)
echo "TELEGRAM_BOT_TOKEN=12345:abc..." >> ~/.comis/.env

# Restart after editing the mounted file directly
docker compose restart comis-daemon

For the exact credential names projected by the base Compose file, its entrypoint removes blank values before Comis loads COMIS_ENV_FILE. Explicit non-empty container values retain precedence over the mounted file at load time. In encrypted mode, a value already stored in secrets.db is authoritative over both sources. After setup, prefer comis secrets set <NAME> for encrypted, live-applied updates.

Environment file

Copy .env.docker.example from the repository root as your starting point:

cp .env.docker.example .env

This template contains Compose image, path, and network settings plus blank explicit overrides for Anthropic, OpenAI, Telegram, Discord, Slack, and the gateway token. It deliberately does not define SECRETS_MASTER_KEY; encrypted first boot writes that key to COMIS_ENV_FILE. Put other persistent provider and channel credentials in COMIS_ENV_FILE as well.

Keep API keys out of config.yaml. Use the mounted COMIS_ENV_FILE for first-boot credentials, then the encrypted secret store for managed updates.

Development overrides

The repository includes docker-compose.dev.yml as an explicit development overlay. Compose does not load it automatically, so plain docker compose up keeps the base file’s loopback-only host bindings and production settings.

Development overrides change the following:

Setting	Production	Development
Image variant	slim (bookworm-slim)	default (full bookworm with debugging tools)
Port binding	127.0.0.1:4766	0.0.0.0:4766 (all interfaces)
NODE_ENV	production	development
Resource limits	2G / 2 CPU	4G / 4 CPU
Web dashboard	Requires --profile web	Starts automatically (no profile needed)

Opt in only when you want the broader development posture:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

The development overlay binds the gateway to 0.0.0.0:4766, sets NODE_ENV=development, uses the full image variant, and starts the web dashboard without a profile. Do not use it unintentionally on an untrusted network. Its !override tags require Docker Compose 2.24.4 or newer.

Web dashboard

The web dashboard is built from Dockerfile.web — a 2-stage build:

1. Build stage — node:22-bookworm-slim, installs the @comis/web package and its dependencies, runs pnpm build to produce the Lit SPA
2. Serve stage — nginx:alpine, copies the built SPA into the Nginx html directory with a custom config from docker/nginx.conf

Nginx configuration

The docker/nginx.conf provides:

• SPA fallback — all routes serve index.html via try_files
• API reverse proxy — /api/ requests are proxied to comis-daemon:4766 with HTTP/1.1 upgrade support
• WebSocket proxy — /ws is proxied to the daemon’s WebSocket endpoint with an 86400s (24h) read timeout
• Static asset caching — JS, CSS, images, and fonts get 30-day cache headers with Cache-Control: public, immutable

The dashboard runs on port 8080 with a health check via wget.

CI/CD

The repository ships two automated Docker workflows:

Workflow	Registry	Trigger
docker-release.yml	GitHub Container Registry (ghcr.io)	Push to main or v* tag; pull requests that change Dockerfile, Dockerfile.web, or .dockerignore
dockerhub-release.yml	Docker Hub (comisai/comis)	v* tag only

Both workflows build multi-arch manifests (linux/amd64 + linux/arm64) and produce both default and slim variants. The Docker Hub workflow version tags are derived directly from the git tag — pushing vX.Y.Z produces comisai/comis:X.Y.Z, comisai/comis:X.Y, and comisai/comis:latest (plus the matching -slim variants).

For full details on image tags, required secrets, and manual publishing, see the Docker Hub Publishing page.

Updating

To update Comis to a new version:

# Pull latest code
git pull

# Rebuild and restart
docker compose up -d --build

If using the web dashboard:

docker compose --profile web up -d --build

The mounted /home/comis/.comis volume preserves your data across rebuilds. Only the application code is replaced.

Related pages

Install with Docker

Quick-start Docker setup for getting started.

Reverse Proxy

Put Comis behind Nginx or Caddy for TLS and custom domains.

Daemon

How the daemon starts, runs, and shuts down.

Troubleshooting

Solutions to common issues.