Docker Setup

Octipus runs as a multi-container Docker application with three services:

Service	Image	Purpose
`octipus-app`	Custom (Bun + Next.js)	API backend + web frontend
`octipus-db`	pgvector/pgvector:pg16	PostgreSQL with vector extensions
`octipus-valkey`	valkey/valkey:7.2-alpine	Caching and pub/sub (Redis-compatible)

The repository’s root docker-compose.yml defines all three. The app container points DATABASE_URL / REDIS_URL at the octipus-db / octipus-valkey service names automatically, so the only values you must supply are the three security keys.

Quick Start

# From the cloned repo root. Generate the three required secrets and put them
# in .env.docker (the compose env_file), e.g.:
cat > .env.docker <<EOF
MASTER_KEY=$(openssl rand -hex 32)
JWT_SECRET=$(openssl rand -hex 32)
SESSION_SECRET=$(openssl rand -hex 32)
EOF

# Build and start the full stack (app + db + cache)
docker compose up --build -d

# View logs
docker compose logs -f octipus

The backend runs migrations on first boot — no manual migrate step. Once it’s up, complete admin + model setup against the container from your host:

octi setup --remote http://localhost:3015

Then open the web UI at http://localhost:3017.

Default Ports

The compose file maps host ports to the in-container ports (host → container):

Service	Host port	Container port	Env override
API	`3015`	`3005`	`OCTIPUS_API_PORT`
Web UI	`3017`	`3007`	`OCTIPUS_WEB_PORT`
PostgreSQL	`5442`	`5432`	`POSTGRES_PORT`
Valkey	`6389`	`6379`	`REDIS_PORT`

Volumes

Volume	Container Path	Purpose
`octipus-workspace`	`/data/workspace`	Agent workspace (files created by agents)
`octipus-documents`	`/data/documents`	Uploaded documents
`octipus-extensions`	`/data/extensions`	Plugins and extensions
`octipus-pgdata`	PostgreSQL data	Database persistence
`octipus-valkey`	Valkey data	Cache persistence

Container CLI Tools

The container includes these tools for agent shell access:

Category	Tools
Core	bash, curl, wget, git, ca-certificates
Text/Data	jq, sed, awk, grep, ripgrep, less
Files	tree, file, zip, unzip, tar, gzip, rsync
Build	make, bun
Scripting	python3 (minimal)
Remote	openssh-client (ssh, scp, sftp)

What Works vs. What Doesn’t

Works

Filesystem — full access within mounted volumes
Shell — commands run inside the container using installed tools
Git — fully functional (SSH keys need mounting)
Browser Extension — runs in user’s real browser, connects via WebSocket
Playwright — headless browser inside the container
Database & Valkey — full access
MCP Servers — SSE transport works; stdio-based must be installed in the container
Network — full outbound access

Does Not Work

Capability	Reason	Workaround
Host CLI tools	Container isolation	Install in Dockerfile or use Docker socket
Host filesystem	Only mounted volumes visible	Add bind mounts in `docker-compose.yml`
Host processes	Container isolation	Use Docker socket for other containers
GUI applications	No display server	Use browser extension (runs on host)

Docker Socket (Sibling Containers)

The Docker socket is mounted into the container, allowing Octipus to spawn sibling containers on the host’s Docker engine:

volumes:
  - //var/run/docker.sock:/var/run/docker.sock

This enables running language-specific tools, building Docker images, and managing other containers. Docker socket access is powerful — only enable in trusted environments.

Adding Host Directory Access

services:
  octipus:
    volumes:
      - /path/on/host:/data/workspace/host-files:ro  # read-only
      - ~/projects:/data/workspace/projects           # read-write

Mount into subdirectories of /data/workspace so agents can access them via the filesystem tool.

Rebuilding

# Rebuild and restart (preserves data volumes)
docker compose down && docker compose up --build -d

# Full reset (deletes all data)
docker compose down -v && docker compose up --build -d