Configuration

Octipus separates the values required to open storage from settings that can be loaded afterward.

• Bootstrap environment: storage mode, database connection, encryption and session secrets, and bind address.
• Database settings: model, channel, workspace, and feature configuration.
• Vault: encrypted provider credentials and other secrets referenced by settings.

npm run setup creates the initial configuration. Use the web Settings and Secrets pages for later runtime changes.

Keep bootstrap secrets stable

Back up the generated secrets. Changing an encryption key directly can make existing encrypted values unreadable. Use the repository’s documented key-rotation script and its dry-run mode.

Storage

For a local evaluation, choose STORAGE_MODE=embedded; PGlite stores data locally. For external storage, set the PostgreSQL connection values described in .env.example. PostgreSQL provides persistence, vector search, caching, queues, and pub/sub.

Precedence

Process environment and .env make boot possible. On first setup, supported values can seed database settings. Thereafter, persisted settings are generally authoritative. A few bootstrap values necessarily remain environment-controlled, and some changes require restart. See Configuration Precedence for the detailed rules.