Environment Variables

All CoreCube configuration is done through environment variables. They can be set in Docker Compose, as Docker secrets (using the _FILE suffix), or directly in the shell for native Bun deployments.

Core settings

Variable	Default	Required	Description
PORT	7400	No	HTTP server port
DATA_DIR	/data	No	Persistent data directory for SQLite, encryption key, and uploaded files
CUBE_ADMIN_EMAIL	admin@example.com	No	Initial admin user email. Skips the setup wizard if set together with CUBE_ADMIN_PASSWORD
CUBE_ADMIN_PASSWORD	changeme123	No	Initial admin user password. Must be changed after first login

Database

Variable	Default	Required	Description
KNOWLEDGE_BACKEND	pgvector	No	pgvector for PostgreSQL + vector search, or sqlite for SQLite FTS only
PGVECTOR_URL	—	Yes (pgvector mode)	PostgreSQL connection string: postgresql://user:password@host:5432/dbname

:::tip Production recommendation Always use pgvector mode for production. SQLite FTS provides keyword-only search and is suitable only for evaluation or very small corpora (< 10K chunks). :::

Security

Variable	Default	Required	Description
ENCRYPTION_KEY	auto-generated	Recommended	AES-256-GCM encryption key for connector credentials, webhook secrets, and LLM API keys. A key is auto-generated on first startup and saved to DATA_DIR/encryption.key
SESSION_MAX_AGE_HOURS	168	No	Session lifetime in hours. Default is 7 days. Sliding expiry — refreshed on each request

:::danger Protect the encryption key If the encryption key is lost, all connector credentials and LLM API keys become permanently unreadable and must be re-entered. Back up DATA_DIR/encryption.key separately. :::

Key rotation

docker exec corecube corecube rotate-key

The server must be stopped during key rotation. The CLI decrypts all credentials with the old key and re-encrypts with the new key in a single transaction.

Docker secrets

Any environment variable supports the _FILE suffix to load its value from a file (e.g., Docker secrets or Kubernetes secrets):

environment:
  ENCRYPTION_KEY_FILE: /run/secrets/encryption_key
  PGVECTOR_URL_FILE: /run/secrets/pgvector_url
  CUBE_ADMIN_PASSWORD_FILE: /run/secrets/admin_password

secrets:
  encryption_key:
    file: ./secrets/encryption_key.txt
  pgvector_url:
    file: ./secrets/pgvector_url.txt
  admin_password:
    file: ./secrets/admin_password.txt

Setup initialization precedence

Environment variables take priority over the setup wizard. The wizard only appears for configuration that env vars don't cover:

1. If CUBE_ADMIN_EMAIL + CUBE_ADMIN_PASSWORD are set → admin user auto-created, wizard user step skipped
2. If KNOWLEDGE_BACKEND + PGVECTOR_URL are set → database auto-configured, wizard database step skipped
3. If env vars cover all steps → wizard skipped entirely (headless bootstrap for CI/CD)
4. If env vars are partial → wizard pre-fills configured values and skips completed steps

Dual database architecture

CoreCube uses two databases with different responsibilities:

Database	Purpose
SQLite (bun:sqlite)	Configuration, users, sessions, connections, API keys, audit logs, settings, background jobs
PostgreSQL + pgvector	Evidence chunks, embeddings, entities, document versions, provenance, attachments

The SQLite database is stored at DATA_DIR/corecube.db. The PostgreSQL database is specified by PGVECTOR_URL.