Installation

System requirements

Octipus runs on Linux, macOS, and Windows. The backend runs on Bun; the web UI is a Next.js app that needs Node.js.

Dependency	Version	Purpose
Bun	≥ 1.1.0	Runtime for the backend, tests, and scripts
Node.js	≥ 18	Required by the Next.js web UI
Git	any	Cloning the repository

That’s everything you need for embedded storage mode. External mode adds the backing services below.

Install Bun

Linux / macOS

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

Windows

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

Get the code

git clone https://github.com/PatriceA/octipus.git
cd octipus
bun install
cd web && bun install && cd ..

Then run bun run setup (see Quick Start) to generate secrets and pick a storage mode.

Storage modes

Octipus picks where it stores data from a single setting, STORAGE_MODE:

Mode	Backing services	Best for
embedded	None — PGlite + in-memory cache	First run, single-user, laptops
external	PostgreSQL + pgvector and Valkey	Multi-user, production

Note

Embedded mode stores its data under ~/.octipus/data by default (override with DATA_DIR). No Docker, no Postgres, no Valkey — just bun run setup and bun run start:all.

Backing services (external mode only)

The repository ships its own docker-compose.yml that defines exactly the two services external mode needs — Postgres (with pgvector) and Valkey. From the repo root:

# Start just the database + cache (not the app container)
docker compose up -d octipus-db octipus-valkey

Service	Image	Host → container port	Notes
octipus-db	pgvector/pgvector:pg16	5442 → 5432	Postgres + pgvector; DB octipus is created automatically
octipus-valkey	valkey/valkey:7.2-alpine	6389 → 6379	Redis-compatible cache / pub-sub / queues

The Postgres container creates the octipus database and user on first boot, and the backend creates the vector / uuid-ossp extensions and runs all migrations automatically when it starts — there are no manual psql or migrate steps.

Point your .env at these services (the wizard does this for you):

STORAGE_MODE=external
DATABASE_URL=postgresql://octipus:octipus@localhost:5442/octipus
REDIS_URL=redis://localhost:6379

Tip

Want the whole stack (app + db + cache) in containers instead of running the backend on your host? Use docker compose up -d and follow Docker Setup.

Optional dependencies

None of these are required to run Octipus. Configure them later from the web UI — credentials live in the encrypted vault, not your .env.

Dependency	Purpose
Ollama	Local LLM inference (the setup wizard can recommend models that fit your hardware)
LiteLLM	Unified proxy for many providers
SearXNG	Self-hosted meta-search for the web-search tool
Provider API keys	OpenAI, Anthropic, Gemini, Grok, DeepSeek, OpenRouter, Voyage
Telegram / Slack / Teams / WhatsApp	Chat channel integrations
Playwright browsers	Browser-automation tool (bunx playwright install)
Claude Code / Gemini CLI / Codex	Subscription-based CLI providers