Docker Setup

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

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

Quick Start

# Copy and configure environment
cp .env.example .env.docker

# Build and start
docker compose up --build -d

# View logs
docker compose logs -f assistant

Default Ports

Port	Default	Env Variable
API	3015	`OCTIPUS_API_PORT`
Web UI	3017	`OCTIPUS_WEB_PORT`
PostgreSQL	5442	`POSTGRES_PORT`
Redis	6389	`REDIS_PORT`

Volumes

Volume	Container Path	Purpose
`assistant-workspace`	`/data/workspace`	Agent workspace (files created by agents)
`assistant-documents`	`/data/documents`	Uploaded documents
`assistant-extensions`	`/data/extensions`	Plugins and extensions
`assistant-pgdata`	PostgreSQL data	Database persistence
`assistant-redis`	Redis 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 & Redis — 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:
  assistant:
    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