Configuration

This guide covers environment variables for installing and fine-tuning Shield360.

Note

ClickHouse connection at runtime is a Database Config, not a live env lookup.
INIT_DB_* variables seed the first Database Config when Shield360 is first set up. Day-2 host, password, or environment changes belong in Organisation → Database Config and Connectors. See also Connectors and Signal routing.

ClickHouse bootstrap (INIT_DB_*)

Used once at seed/install time to create the default Database Config. After that, the UI (and APIs under /api/db-config) own the connection.

Env var	Database Config field
INIT_DB_HOST	Host
INIT_DB_PORT	Port
INIT_DB_DATABASE	Database
INIT_DB_USERNAME	Username
INIT_DB_PASSWORD	Password

Environment variables

INIT_DB_HOST required

Seed-only: host address written into the default Database Config on first setup. Not read on every request after the config exists.

Example:

export INIT_DB_HOST=127.0.0.1

INIT_DB_PORT required

Seed-only: ClickHouse HTTP port for the default Database Config (commonly 8123).

Example:

export INIT_DB_PORT=8123

INIT_DB_DATABASE required

Seed-only: ClickHouse database name for the default Database Config.

Example:

export INIT_DB_DATABASE=default

INIT_DB_USERNAME required

Seed-only: username stored on the default Database Config.

Example:

export INIT_DB_USERNAME=default

INIT_DB_PASSWORD required

Seed-only: password stored on the default Database Config. Rotate later via the Database Config UI, not by relying on this env var alone.

Example:

export INIT_DB_PASSWORD=default

SQLITE_DATABASE_URL required

Sets the location where SQLITE data is stored.

Example:

export SQLITE_DATABASE_URL=file:/app/client/data/data.db

OAuth authentication variables

Note

For detailed OAuth setup instructions, see the OAuth Authentication Setup guide.

NEXTAUTH_URL

Sets the canonical URL of your site for NextAuth.js authentication

Example:

export NEXTAUTH_URL=http://localhost:3000

NEXTAUTH_SECRET

Used to encrypt the NextAuth.js JWT tokens and email verification hashes

Example:

export NEXTAUTH_SECRET=your-secret-here

Generate with: openssl rand -base64 32

GOOGLE_CLIENT_ID

Google OAuth client ID for Google sign-in integration

Example:

export GOOGLE_CLIENT_ID=your-google-client-id

GOOGLE_CLIENT_SECRET

Google OAuth client secret for Google sign-in integration

Example:

export GOOGLE_CLIENT_SECRET=your-google-client-secret

GITHUB_CLIENT_ID

GitHub OAuth client ID for GitHub sign-in integration

Example:

export GITHUB_CLIENT_ID=your-github-client-id

GITHUB_CLIENT_SECRET

GitHub OAuth client secret for GitHub sign-in integration

Example:

export GITHUB_CLIENT_SECRET=your-github-client-secret

Server variables

PORT

Sets the port the Shield360 server listens on. For Docker Compose deployments, set this in the .env file next to docker-compose.yml - Compose maps it to both the host port and the container’s internal DOCKER_PORT for you. For Kubernetes or a raw container run, set DOCKER_PORT directly instead (see below); the container’s entrypoint always derives its actual listening port from DOCKER_PORT, defaulting to 3000 if unset.

Example (Docker Compose .env):

PORT=3000

DOCKER_PORT

Sets the port the Shield360 container listens on internally. Only relevant for Kubernetes or a raw container run where there’s no Docker Compose translating PORT for you.

Example:

export DOCKER_PORT=3000

API_URL

Sets the base URL Shield360 uses to call back into its own API - required by the Auto Evaluation, Auto Pricing, Agents materialization, and telemetry-snapshot cron jobs, which run as separate processes and call this URL directly. Defaults to http://localhost:$PORT. Set this if you run behind a reverse proxy, a non-default host, or a different container/pod hostname - otherwise these background jobs will fail silently after every restart.

Example:

export API_URL=https://shield360.internal.example.com

SHIELD360_EDITION

Sets which Shield360 build is running. Defaults to oss if unset.

Example:

export SHIELD360_EDITION=oss

Agents variables

Tune the background job that materializes the Agents page’s call graphs and versions from trace data.

AGENTS_MATERIALIZE_SCHEDULE

Cron schedule for the Agents materialization job. Defaults to * * * * * (every minute); the job self-throttles when there’s no new trace data to process.

Example:

export AGENTS_MATERIALIZE_SCHEDULE="* * * * *"

AGENTS_MATERIALIZE_MAX_PER_TICK

Maximum number of agents materialized per scheduled run. Defaults to 100.

Example:

export AGENTS_MATERIALIZE_MAX_PER_TICK=100

AGENTS_MATERIALIZE_PARALLEL

Maximum number of agents materialized concurrently per run. Defaults to 4.

Example:

export AGENTS_MATERIALIZE_PARALLEL=4

AGENTS_LOG_LEVEL

Log level for the Agents materialization job (debug, info, warn, error). Defaults to info.

Example:

export AGENTS_LOG_LEVEL=info

AGENTS_LOG_STACK

Set to false to omit stack traces from Agents materialization error logs. Defaults to including them.

Example:

export AGENTS_LOG_STACK=false

Telemetry variables

Note

See Anonymous Telemetry for what Shield360’s own usage telemetry collects and why.

TELEMETRY_ENABLED

Set to false to disable Shield360’s anonymous usage telemetry, including the daily instance snapshot.

Example:

export TELEMETRY_ENABLED=false

TELEMETRY_SNAPSHOT_SCHEDULE

Cron schedule for the daily anonymous instance telemetry snapshot. Defaults to 17 3 * * *.

Example:

export TELEMETRY_SNAPSHOT_SCHEDULE="17 3 * * *"

Security variables

Shield360 enables stricter API protections by default, including security response headers, CSRF checks for browser session API requests, vault secret encryption, and restricted CORS for the vault secrets API.

CRON_JOB_SECRET

Token required to trigger internal cron-driven endpoints (Auto Evaluation, Auto Pricing, Agents materialization, telemetry snapshot). Optional for typical self-hosted installs - when unset, both the cron scripts and the endpoint check fall back to the same shared default, so scheduled jobs work out of the box with no configuration. Set it only if your instance is exposed such that an untrusted party could otherwise call these endpoints directly.

Changing this takes effect on the next restart, since cron entries are re-created from the current environment on every server startup.

Example:

export CRON_JOB_SECRET=your-cron-secret

SHIELD360_REQUIRE_ORG_FILTER

Set to true to enforce organisation-scoped isolation on coding-agent telemetry queries in multi-organisation deployments.

Example:

export SHIELD360_REQUIRE_ORG_FILTER=true

SHIELD360_VAULT_ENCRYPTION_KEY

Secret used to encrypt Vault values at rest with AES-256-GCM. If this is not set, Shield360 falls back to NEXTAUTH_SECRET.

Use a stable, high-entropy value and keep it unchanged across restarts. Changing this value after secrets are encrypted prevents existing Vault values from being decrypted.

Generate with:

openssl rand -base64 32

Example:

export SHIELD360_VAULT_ENCRYPTION_KEY=your-vault-encryption-key

SHIELD360_ALLOWED_CORS_ORIGINS

Comma-separated list of browser origins that are allowed to call API-key authenticated Vault secret retrieval from another domain.

Configure this when a browser application hosted on a different origin needs to call POST /api/vault/get-secrets. Server-to-server SDK or REST calls usually do not need this because they do not send a browser Origin header.

Specify complete origins, including scheme and host. Do not use *.

Example:

export SHIELD360_ALLOWED_CORS_ORIGINS=https://app.example.com,https://admin.example.com

SHIELD360_ALLOWED_ORIGINS

Backward-compatible alias for SHIELD360_ALLOWED_CORS_ORIGINS.

Example:

export SHIELD360_ALLOWED_ORIGINS=https://app.example.com

Note

NEXTAUTH_URL is also treated as an allowed same-site origin for Vault CORS checks. Browser requests from other domains must be listed in SHIELD360_ALLOWED_CORS_ORIGINS or SHIELD360_ALLOWED_ORIGINS.

Environment file placement

Environment variables can be configured in multiple ways depending on your deployment method:

Development setup

Client-side .env

Create a .env file in the src/client/ directory for development:

src/client/.env

This file is automatically loaded by Next.js during development.

Docker Compose .env

Create a .env file in the same directory as your docker-compose.yml file:

# In the root directory with docker-compose.yml
.env

This file is automatically loaded by Docker Compose.

Development Docker Compose .env

For development Docker setup, create a .env file alongside src/dev-docker-compose.yml:

# In the src/ directory with dev-docker-compose.yml
src/.env

Production setup

For production deployments, set environment variables directly in your hosting platform or container orchestration system (Kubernetes, Docker Swarm, etc.).

Applying changes at runtime

Shield360 reads environment variables once when the server process starts - there’s no hot-reload, so a config change (editing a .env file, updating a Kubernetes Secret, etc.) only takes effect after you restart the container or process.

A restart is also all you need for the cron-driven features (Auto Evaluation, Auto Pricing, Agents materialization, telemetry snapshot): their scheduled jobs are re-created from the current environment on every startup, so there’s no separate step to “re-save” settings after changing something like API_URL, CRON_JOB_SECRET, or AGENTS_MATERIALIZE_SCHEDULE.

Sample environment file (.env)

# ClickHouse bootstrap ONLY — seeds the first Database Config at install.
# Day-2 host/password/environment changes: Organisation → Database Config.
INIT_DB_HOST="127.0.0.1"
INIT_DB_PORT="8123"
INIT_DB_DATABASE="default"
INIT_DB_USERNAME="default"
INIT_DB_PASSWORD="SHIELD360"
SQLITE_DATABASE_URL="file:/app/client/data/data.db"

# NextAuth Configuration (Optional)
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-here"

# OAuth Providers (Optional)
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

# Server Configuration (Optional)
# PORT is for Docker Compose; use DOCKER_PORT instead for Kubernetes or a raw container run
PORT="3000"
API_URL="http://localhost:3000"

# Agents Materialization (Optional)
AGENTS_MATERIALIZE_SCHEDULE="* * * * *"

# Telemetry (Optional)
TELEMETRY_ENABLED="true"

# Security Configuration (Optional)
SHIELD360_VAULT_ENCRYPTION_KEY="your-vault-encryption-key"
SHIELD360_ALLOWED_CORS_ORIGINS="https://app.example.com,https://admin.example.com"
CRON_JOB_SECRET="your-cron-secret"

---

Create a dashboard

Create custom visualizations with flexible widgets, queries, and real-time AI monitoring

Manage prompts

Version, deploy, and collaborate on prompts with centralized management and tracking

LLM playground

Compare cost, duration, and response tokens across different LLMs to find the most efficient model