Docker

The official Codius Docker image runs the daemon and serves the bundled browser UI from the same HTTP origin. It is meant for servers, dev boxes, NAS devices, homelab hosts, and other places where you want Codius running without the desktop app.

Docker images follow the stable Codius release cadence. ghcr.io/CodiusAI/codius-app:latest points at the latest stable release, not an arbitrary main build.

docker run -d --name codius \
  -p 6767:6767 \
  -e CODIUS_PASSWORD=change-me \
  -v "$PWD/codius-home:/home/codius" \
  -v "$PWD:/workspace" \
  ghcr.io/CodiusAI/codius-app:latest

Then open:

http://localhost:6767

If you set CODIUS_PASSWORD, use that same password when adding the direct daemon connection in the web UI, mobile app, or Codius CLI.

What the image includes

The image:

• installs the Codius daemon and Codius CLI
• serves the bundled web UI
• listens on 0.0.0.0:6767 inside the container
• stores daemon state under /home/codius/.codius
• runs the daemon and launched agents as the non-root codius user

The image does not bundle agent CLIs such as Claude Code, Codex, OpenCode, Copilot, or Pi. Add the agents you use with a small child image.

Docker Compose

services:
  codius:
    image: ghcr.io/CodiusAI/codius-app:latest
    container_name: codius
    restart: unless-stopped
    ports:
      - "6767:6767"
    environment:
      CODIUS_PASSWORD: "change-me"
      # CODIUS_HOSTNAMES: "codius.example.com,.lan"
    volumes:
      - ./codius-home:/home/codius
      - ./workspace:/workspace

Start it:

docker compose up -d

Install agent CLIs

Create a child image for the providers you want available:

FROM ghcr.io/CodiusAI/codius-app:latest

USER root
RUN npm install -g @openai/codex @anthropic-ai/claude-code opencode-ai

Build it:

docker build -t codius-with-agents .

Then use image: codius-with-agents in Compose.

Leave the child image user as root. The base entrypoint uses root only for first-run mounted-volume setup, then drops the daemon and launched agents to the non-root codius user.

You can authenticate agents either by passing provider environment variables or by running the provider login flow inside the container:

docker exec -it --user codius codius codex
docker exec -it --user codius codius claude

Agent credentials persist in /home/codius.

Volumes

Mount two paths for most deployments:

On Linux, the built-in codius user is uid/gid 1000:1000. Make mounted directories writable by that user, or run the container with Docker's --user / Compose user: option.

Reverse proxy

Forward normal HTTP traffic and WebSocket upgrades to the container.

Caddy:

codius.example.com {
  reverse_proxy 127.0.0.1:6767
}

Nginx:

server {
    listen 443 ssl;
    server_name codius.example.com;

    location / {
        proxy_pass http://127.0.0.1:6767;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

If you reach Codius by DNS name, allow that host:

environment:
  CODIUS_HOSTNAMES: "codius.example.com,.lan"

IPs and localhost are allowed by default.

Security

Set CODIUS_PASSWORD for any published port or network-reachable deployment. Use HTTPS at your reverse proxy for browser access outside localhost.

The static web UI is public on the daemon origin. The daemon API and WebSocket are protected by password auth when configured.

Agents can access whatever you mount into /workspace and whatever credentials you place in /home/codius. Keep those mounts scoped to what the agents should be able to use.

See Security for the full daemon trust model.

Troubleshooting

• The UI loads but cannot connect: if CODIUS_PASSWORD is set, add a direct connection with the same password.
• 403 Host not allowed: set CODIUS_HOSTNAMES to the DNS names you use.
• Provider not available: install that agent CLI in a child image or make sure the binary is on PATH.
• Permission errors in /workspace: make the mounted directory writable by uid/gid 1000:1000, or run the container as the host uid/gid.
• Logs: run docker logs codius, or inspect /home/codius/.codius/daemon.log inside the container.