Installation

System Requirements

Octipus runs on Linux, macOS, and Windows. The backend requires Bun as its runtime, and the web UI requires Node.js for Next.js.

Required Dependencies

Dependency	Version	Purpose
Bun	>= 1.1.0	Runtime for backend, tests, scripts
Node.js	>= 18	Required by Next.js web UI
Docker	any	Runs PostgreSQL, Redis, Ollama
PostgreSQL	15	Database (via pgvector/pgvector:pg15 Docker image)
Redis	any	Caching, sessions, pub/sub, queues

Optional Dependencies

Dependency	Purpose
Ollama	Local LLM inference (runs via Docker)
LiteLLM	Unified proxy for OpenAI, Anthropic, Ollama
SearXNG	Meta-search engine for web search skill
Telegram Bot Token	Telegram channel support
Slack App Tokens	Slack channel support
Teams App Credentials	Microsoft Teams channel support
Playwright browsers	Browser automation skill (bunx playwright install)
Claude Code / Gemini CLI / Codex	Free subscription-based CLI model providers

Docker Services

Octipus uses shared Docker services from a docker-compose.yml. These must be running before starting Octipus.

# Start required services
cd ~/docker-services
docker compose up -d db redis

# Start optional services
docker compose up -d ollama litellm searxng

Service Reference

Service	Port	Image	Required
PostgreSQL	5432	pgvector/pgvector:pg15	Yes
Redis	6379	redis:alpine	Yes
Ollama	11434	ollama/ollama:rocm	No
Ollama 2	11435	ollama/ollama:rocm	No
LiteLLM	4000	ghcr.io/berriai/litellm:main-latest	No
SearXNG	8888	searxng/searxng:latest	No
N8N	5678	n8nio/n8n	No
Open WebUI	3000	ghcr.io/open-webui/open-webui:main	No

Note

The Ollama images use ollama/ollama:rocm for AMD GPU support. If you have an NVIDIA GPU, use ollama/ollama instead.

Installing Bun

Linux / macOS

curl -fsSL https://bun.sh/install | bash

Windows

powershell -c "irm bun.sh/install.ps1 | iex"

Database Setup

After starting PostgreSQL via Docker, create the database and required extensions:

# Create the database (if it doesn't exist)
docker exec <db-container> psql -U <superuser> -c "CREATE DATABASE assistant;"

# Install required extensions
docker exec <db-container> psql -U <superuser> -d assistant \
  -c "CREATE EXTENSION IF NOT EXISTS vector;"
docker exec <db-container> psql -U <superuser> -d assistant \
  -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp";'

Tip

The vector and uuid-ossp extensions require superuser privileges. The assistant application user can use them once they are created. If the vector extension cannot be created, the application logs a warning and continues without vector search capabilities.