Skip to content

docker.md

Latest commit

 

History

History
238 lines (180 loc) · 7.05 KB

docker.md

File metadata and controls

238 lines (180 loc) · 7.05 KB
Raw

Running Otto in Docker

Otto publishes a container image for running the daemon on a server, VM, NAS, or homelab box. The image also serves the bundled browser web UI, so one container gives you both the daemon API and a self-hosted UI.

The image source lives in docker/.

How it works

The official image:

  • builds @otto-code/server and @otto-code/cli from source-built workspace tarballs
  • runs the daemon as the non-root otto user
  • listens on 0.0.0.0:6868 inside the container
  • enables the bundled daemon web UI with OTTO_WEB_UI_ENABLED=true
  • stores daemon state and agent credentials under /home/otto
  • leaves agent CLIs out of the base image

Open the container's HTTP origin, for example http://localhost:6868, to load the web UI. The served app receives a same-origin connection hint and connects back to that daemon. Static UI files load without daemon auth; API and WebSocket requests still require OTTO_PASSWORD when one is configured.

Quick Start

docker run -d --name otto \
  -p 6868:6868 \
  -e OTTO_PASSWORD=change-me \
  -v "$PWD/otto-home:/home/otto" \
  -v "$PWD:/workspace" \
  ghcr.io/draek2077/otto:latest

Then open:

http://localhost:6868

If you set OTTO_PASSWORD, enter the same password when adding the direct daemon connection in the web UI or another Otto client.

Docker Compose

Use docker/docker-compose.example.yml:

cp docker/docker-compose.example.yml docker-compose.yml
$EDITOR docker-compose.yml
docker compose up -d

Minimal example:

services:
  otto:
    image: ghcr.io/draek2077/otto:latest
    restart: unless-stopped
    ports:
      - "6868:6868"
    environment:
      OTTO_PASSWORD: "change-me"
    volumes:
      - ./otto-home:/home/otto
      - ./workspace:/workspace

Installing Agents

The base image does not preinstall Claude Code, Codex, OpenCode, Copilot, Pi, or other agent CLIs. That keeps the default image small and avoids coupling Otto releases to third-party agent release cycles.

Create a child image for the agents you use:

FROM ghcr.io/draek2077/otto:latest

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

Build it:

docker build -f Dockerfile -t otto-with-agents .

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

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

An example child image is in docker/Dockerfile.agents.example.

You can also mount credentials from the host or run agent login once inside the container:

docker exec -it --user otto otto codex
docker exec -it --user otto otto claude

Agent credentials and config persist in /home/otto, alongside daemon state. Provider environment variables such as OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENAI_BASE_URL, or ANTHROPIC_BASE_URL can be passed through docker run -e or compose.environment; Otto passes them to launched agents.

Volumes

Mount Purpose
/home/otto Otto state under .otto plus agent config such as .codex, .claude
/workspace Code that Otto and launched agents can read and write

The image defaults:

Variable Default
HOME /home/otto
OTTO_HOME /home/otto/.otto
OTTO_LISTEN 0.0.0.0:6868

If you bind-mount host directories on Linux, make sure the container user can write them. The built-in otto user has uid/gid 1000:1000. For a different host uid/gid, either adjust ownership on the mounted directories or run the container with Docker's --user / Compose user: option.

Reverse Proxies

When serving Otto behind a reverse proxy, forward normal HTTP requests and WebSocket upgrades to the same daemon port.

Caddy example:

otto.example.com {
  reverse_proxy 127.0.0.1:6868
}

Nginx example:

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

    location / {
        proxy_pass http://127.0.0.1:6868;
        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 the daemon by DNS name, set OTTO_HOSTNAMES so host-header validation allows that name:

environment:
  OTTO_HOSTNAMES: "otto.example.com,.lan"

IPs and localhost are allowed by default.

Security

  • Set OTTO_PASSWORD for any published port or network-reachable deployment.
  • Prefer HTTPS at the reverse proxy for direct browser access.
  • Use the Otto relay for untrusted networks or mobile access when you do not want to expose the daemon port directly.
  • The container is the isolation boundary for agents. Agents can read and write whatever you mount into /workspace and whatever credentials you place in /home/otto.
  • The bundled web UI static files are public on the daemon origin. The daemon API and WebSocket remain protected by password auth when configured.

See SECURITY.md for the daemon trust model.

Building Locally

docker build -f docker/base/Dockerfile -t otto:local .

To assert the source tree version while building:

docker build \
  --build-arg OTTO_VERSION=0.1.102 \
  -t otto:0.1.102 \
  -f docker/base/Dockerfile \
  .

The Docker workflow builds the image on pull requests and on main as a non-publishing check. Stable vX.Y.Z tag pushes publish ghcr.io/draek2077/otto:X.Y.Z and ghcr.io/draek2077/otto:latest. Beta tags publish only the exact prerelease tag, such as ghcr.io/draek2077/otto:0.1.102-beta.1, and do not update latest.

To replace a Docker image in place without rebuilding desktop, APK, or EAS mobile release artifacts, dispatch the Docker workflow manually instead of pushing a v* release tag:

gh workflow run docker.yml \
  --ref main \
  -f otto_version=0.1.102-beta.1 \
  -f publish=true

Manual Docker publishes require an explicit otto_version. The workflow builds from the checked-out source tree and publishes only the exact prerelease image tag for prerelease versions.

The published image is multi-arch for linux/amd64 and linux/arm64.

Troubleshooting

  • The web UI loads but cannot connect: if OTTO_PASSWORD is set, add a direct connection with the same password.
  • 403 Host not allowed: set OTTO_HOSTNAMES to the DNS names you use.
  • Provider not available: install that agent CLI in a child image or mount a runtime where 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: inspect docker logs otto or /home/otto/.otto/daemon.log inside the container.