Configuration | CodeVector Docs

CodeVector is configured entirely through environment variables. Set them however your container orchestrator expects: an .env file, a Kubernetes Secret, a cloud secrets manager, or your CI/CD’s environment configuration. All required values are validated at startup; the app fails fast with a clear error if anything is missing.

Required variables

Variable	Description	Example
`DOMAIN`	Public hostname served by this deployment	`gateway.example.com`
`ACME_EMAIL`	Let’s Encrypt registration email	`ops@example.com`
`POSTGRES_PASSWORD`	Postgres superuser password	Strong random string
`SESSION_SECRET`	Exactly 32 characters for session cookie signing	`openssl rand -hex 16`
`KEK_PRIMARY`	Minimum 32 characters for envelope encryption	`openssl rand -hex 32`
`LICENSE_TOKEN`	Signed license token from CodeVector	Contact CodeVector team

Optional variables

Variable	Default	Description
`POSTGRES_USER`	`postgres`	Postgres username
`POSTGRES_DB`	`codevector`	Postgres database name
`DATABASE_URL`	Auto-built	Override for external/managed Postgres
`GATEWAY_PUBLIC_URL`	`https://${DOMAIN}`	Override if TLS terminates outside the stack
`KEK_SECONDARY`	-	Previous KEK during rotation
`SMTP_HOST`	-	SMTP server for email (leave empty to disable)
`SMTP_PORT`	`587`	SMTP port
`SMTP_USER`	-	SMTP username
`SMTP_PASSWORD`	-	SMTP password
`SMTP_FROM`	-	From address for outgoing email
`LOG_LEVEL`	`info`	Log verbosity
`LOG_FORMAT`	`json`	Log format (`json` or `text`)
`RETENTION_MONTHS`	`13`	Audit log retention
`ENABLE_REMOTE_CATALOG`	`false`	Sync model catalog from a remote URL
`CATALOG_SYNC_URL`	-	Remote catalog endpoint
`CATALOG_SYNC_PUBKEY`	-	Ed25519 public key for catalog signature verification

Rate limit and budget enforcement

Variable	Default	Description
`RATE_LIMIT_OUTPUT_OVERAGE_POLICY`	`reject`	What to do when a request’s worst-case output reservation can’t fit a user’s per-minute output cap: `reject` (return 429) or `clamp` (shrink the request’s `max_tokens` to the remaining bucket and forward). See the rate limits guide for the tradeoff.
`RATE_LIMIT_DEFAULT_MAX_OUTPUT_TOKENS`	`8192`	Reservation fallback used for cap math when both the request’s `max_tokens` and the model’s catalog default are absent. In `reject` mode this never modifies the outgoing request; in `clamp` mode it becomes the clamp ceiling.
`RATE_LIMIT_ACTIVE_REQUEST_TTL_MS`	`600000`	Maximum age of an in-flight concurrency reservation (10 minutes by default). Reservations older than this are reclaimed automatically, so a gateway crash mid-request does not permanently consume a user’s slot. Raise this only if you have agentic calls that genuinely run longer than 10 minutes.

Secrets modes

Mode A - `.env` file

Simpler. Recommended for single-host deployments.

cp .env.example .env
chmod 600 .env
# edit and paste values

Mode B - Docker / Swarm secrets via `_FILE`

For any secret env var FOO, the app reads FOO_FILE=/path/to/file in place of the plain env var.

Supported: DATABASE_URL, SESSION_SECRET, KEK_PRIMARY, KEK_SECONDARY, LICENSE_TOKEN, SMTP_PASSWORD, CATALOG_SYNC_PUBKEY.

Example compose.override.yml:

secrets:
  session_secret: { external: true }
  kek_primary: { external: true }

services:
  app:
    secrets: [session_secret, kek_primary]
    environment:
      SESSION_SECRET_FILE: /run/secrets/session_secret
      KEK_PRIMARY_FILE: /run/secrets/kek_primary
      SESSION_SECRET: ""
      KEK_PRIMARY: ""

License token

A valid LICENSE_TOKEN is required at startup. To obtain a token, .

Frequently asked questions

How do I get a license token?

. The verifying public key is baked into the image, so once you have a token, just drop it in LICENSE_TOKEN and restart.

Can I use Docker secrets instead of .env?

Yes. The app supports the _FILE convention. Set SESSION_SECRET_FILE, KEK_PRIMARY_FILE, LICENSE_TOKEN_FILE, etc.

What happens if I leave SMTP_HOST empty?

Email is disabled. Invite and password-reset endpoints return 501.

Quickstart. Step-by-step deploy guide.
License. License states and enforcement.