Configuration

Configuration Methods

Octipus can be configured via:

1. Environment variables in a .env file
2. Interactive setup wizard via bun run setup
3. Database settings managed through the web UI Settings page

Port Configuration

Service	Default Port	Env Var
Backend API	3005	API_PORT
WebChat	3006	WEBCHAT_PORT
Web UI	3007	WEB_PORT

Environment Variables

Create a .env file in the project root or use bun run setup to generate one.

Required

# ─── Required ─────────────────────────────────────────────────
DATABASE_URL=postgres://user:password@localhost:5432/octipus
REDIS_URL=redis://localhost:6379

# Security keys (minimum 32 characters each, use `bun run setup` to generate)
MASTER_KEY=your-master-key-at-least-32-characters
JWT_SECRET=your-jwt-secret-at-least-32-characters
SESSION_SECRET=your-session-secret-at-least-32-chars

Tip

Run bun run setup to automatically generate cryptographically secure keys for MASTER_KEY, JWT_SECRET, and SESSION_SECRET.

Server

# ─── Server ───────────────────────────────────────────────────
API_PORT=3005
API_HOST=0.0.0.0
LOG_LEVEL=info
CORS_ORIGINS=http://localhost:3006,http://localhost:3007

Models

# ─── Models ───────────────────────────────────────────────────
LITELLM_URL=http://localhost:4000      # LiteLLM proxy (optional)
OLLAMA_URL=http://localhost:11434      # Local Ollama (optional)
# Default model is configured in the database via the Models page.
# Provider API keys (OpenAI, Anthropic, Gemini) are stored in the encrypted vault.

Note

The default model is stored in the database, not in environment variables. Configure it through the Models page in the web UI.

Channels

# ─── Channels (optional) ─────────────────────────────────────
TELEGRAM_BOT_TOKEN=                    # From @BotFather
SLACK_BOT_TOKEN=                       # xoxb-...
SLACK_APP_TOKEN=                       # xapp-...
TEAMS_APP_ID=
TEAMS_APP_PASSWORD=
WHATSAPP_ACCESS_TOKEN=                 # Meta Cloud API token
WHATSAPP_PHONE_NUMBER_ID=             # From Meta dashboard
WHATSAPP_VERIFY_TOKEN=                 # Webhook verify token
WHATSAPP_APP_SECRET=                   # Meta App Secret

Skills & Agent Limits

# ─── Skills ───────────────────────────────────────────────────
AGENT_MAX_TOKEN_BUDGET=100000         # Per-agent token limit (0 = unlimited)
AGENT_DEFAULT_TIMEOUT=300000          # Per-agent timeout in ms (default: 5min)
AGENT_MAX_ITERATIONS=50               # Max iterations per agent loop

ENABLED_SKILLS=filesystem,shell,git,browser,websearch,docker
WORKSPACE_PATH=./workspace
SEARXNG_URL=http://localhost:8888     # SearXNG meta-search (optional)

Integrations

# ─── Integrations (optional) ─────────────────────────────────
N8N_URL=http://localhost:5678
N8N_API_KEY=
MCP_GATEWAY_URL=http://localhost:8811

Database & Migrations

# ─── Migrations ──────────────────────────────────────────────
SKIP_MIGRATIONS=false                  # Set to true for production deploys

Voice

# ─── Voice (optional) ────────────────────────────────────────
WHISPER_MODEL_PATH=
PIPER_MODEL_PATH=

Configuration Reference

Agent Limits

Variable	Default	Description
AGENT_MAX_TOKEN_BUDGET	100000	Maximum tokens per agent (0 = unlimited). Prevents runaway agents from exhausting provider quotas.
AGENT_DEFAULT_TIMEOUT	300000	Wall-clock timeout per agent in milliseconds (default: 5 minutes).
AGENT_MAX_ITERATIONS	50	Maximum iterations in the agent thought-action-observation loop.

Skills

Variable	Default	Description
ENABLED_SKILLS	filesystem,shell,git,browser,websearch,docker	Comma-separated list of enabled skills.
WORKSPACE_PATH	./workspace	Default working directory for file and shell operations.
SEARXNG_URL	—	URL of the SearXNG instance for web search.

Logging

Variable	Default	Description
LOG_LEVEL	info	Logging verbosity. Options: debug, info, warn, error.

Migrations

Variable	Default	Description
SKIP_MIGRATIONS	false	Skip automatic database migrations on startup. Useful for production where migrations are run separately.