Configuration

How configuration works

Octipus keeps configuration in two places, with a clear split:

1. A minimal .env — only the handful of values needed to boot: which storage mode to use, how to reach the database/cache, and the security keys. Nothing else belongs here.
2. The database (and encrypted vault) — the source of truth at runtime for everything else: model config and provider keys, channel tokens, workspace paths, agent limits, feature flags, ports, and so on. Edit these under Settings → Configuration in the web UI, or via the API.

Env is bootstrap-only

On first boot, any optional values you put in .env are seeded into the DB/vault once (idempotent). After that, the database wins — editing .env later has no effect unless the matching DB row is empty. So there’s no “two sources” risk: .env is bootstrap-only, the DB is canonical. To force a re-seed, clear the _system.envMigrated setting and restart.

The minimal .env

This is the entire .env for a typical install. bun run setup writes it for you (and generates the three secrets). Copy .env.example if you prefer to do it by hand.

# ── Storage mode ────────────────────────────────────────────
# 'embedded' = PGlite + in-memory cache (zero external deps, local dev)
# 'external' = PostgreSQL + pgvector + Valkey (production)
STORAGE_MODE=external

# ── Database + cache (external mode ONLY — omit for embedded) ─
DATABASE_URL=postgresql://octipus:octipus@localhost:5442/octipus
# Valkey is Redis-compatible; the var stays REDIS_URL for client compatibility.
REDIS_URL=redis://localhost:6379

# ── Security keys (required, ≥ 32 chars — `bun run setup` generates these) ─
MASTER_KEY=
JWT_SECRET=
SESSION_SECRET=

# ── API server (optional — these are the defaults) ──────────
API_HOST=127.0.0.1
API_PORT=3005

Variable	Required?	Notes
STORAGE_MODE	Yes	embedded or external
DATABASE_URL	External only	Postgres + pgvector connection string
REDIS_URL	External only	Valkey/Redis connection string
MASTER_KEY	Yes	Vault encryption root (AES-256-GCM). Derives per-user data-encryption keys.
JWT_SECRET	Yes	Signs auth tokens
SESSION_SECRET	Yes	Signs sessions
API_HOST / API_PORT	No	Default 127.0.0.1 / 3005. HOST / PORT also accepted.
DATA_DIR	No	Embedded-mode data dir (default ~/.octipus/data)

Tip

Never hand-write the security keys. bun run setup produces cryptographically secure 64-character values for MASTER_KEY, JWT_SECRET, and SESSION_SECRET.

Ports

Service	Default	Set via
Backend API	3005	API_PORT (env, bootstrap)
Web UI	3007	WEB_PORT (env, bootstrap)
PostgreSQL	5442 → 5432	repo docker-compose.yml (POSTGRES_PORT)
Valkey	6389 → 6379	repo docker-compose.yml (REDIS_PORT)

The container ports above are the repo compose mappings (host → container). When you run the backend natively (bun run start:all) it listens directly on 3005 / 3007.

Everything else lives in the database

You will not find these in .env — set them in the web UI once Octipus is running:

Area	Where to set it
Models & default model	Models page
Provider API keys (OpenAI, Anthropic, Gemini, Grok, DeepSeek, OpenRouter, Voyage)	Encrypted vault (added on the Models / Secrets pages)
Channel tokens (Telegram, Slack, Teams, WhatsApp)	Settings → Channels / vault
Agent limits (token budget, timeout, iterations)	Settings → Configuration
Enabled tools, workspace path	Settings → Configuration
Logging level, CORS origins	Settings → Configuration
Multi-user flags, org/SSO	Admin pages

Advanced: bootstrap overrides

A few of the above (e.g. provider keys, channel tokens, log level) are also readable from .env as a one-time bootstrap convenience for headless/CI installs — but they’re seeded into the DB on first boot and the DB takes over from there. Prefer the web UI; see .env.example for the full optional list.

Configuration methods, in short

1. bun run setup — interactive wizard; writes the minimal .env, registers the admin, optionally wires the first model.
2. .env — the minimal bootstrap values above (and, for CI, optional one-time seeds).
3. Web UI → Settings → Configuration — the canonical place to change anything at runtime.