Environment

Noxus configuration is split between:

runtime env vars (URLs, deployment mode, non-sensitive settings)
secrets (credentials and keys)
admin-managed platform settings (global configuration in the Noxus admin portal)

Configuration Sources

Environment Variable Layers

Layer	Example
Base platform env	deployment env, URLs, storage mode, feature toggles
Service-specific env	frontend-only host binding, worker subscribe mode
Secrets	DB/Redis credentials, auth keys, provider secrets

Environment Variable Reference

Platform

Variable	Default	Description
`DEPLOYMENT_ENV`	`"prod"`	Environment name for logging purposes
`DEPLOYMENT_NAME`	`"NOXUS"`	Display name for the deployment instance
`ON_PREM`	`"false"`	Set to `"true"` for non-cloud based deployments
`ADMIN_EMAIL`	—	Admin email used during initial bootstrap - only used on first boot

URLs

Variable	Default	Description
`BACKEND_URL`	—	Public URL for the backend API (e.g. `https://api.example.com`). Can be set to an internal LB for the frontend instance
`FRONTEND_URL`	—	Public URL for the frontend (e.g. `https://example.com`)
`RELAY_URL`	—	Public URL for the relay service (e.g. `https://relay.example.com`)

Database Configuration

Variable	Default	Description
`DATABASE`	`"spot"`	PostgreSQL database name
`POSTGRES_POOL_SIZE`	`"64"`	Connection pool size for the primary database
`VECTOR_POSTGRES_POOL_SIZE`	`"128"`	Connection pool size for the vector database
`RUN_MIGRATIONS`	`"1"`	Run Alembic migrations on startup

Redis

Variable	Default	Description
`REDIS_PORT`	`"6379"`	Redis server port
`REDIS_SSL`	`""`	Enable SSL for Redis connections
`REDIS_SINGLE_DB_ONLY`	`""`	Restrict to a single Redis database, for compatibility with some managed Redis services
`CACHE_LOCATION`	`"redis"`	Cache backend location

Object Storage

Variable	Default	Description
`BUCKET_CLIENT`	`"s3"`	Storage provider: `gcloud`, `s3`, or `minio`
`STORAGE_BUCKET`	—	Primary storage bucket name
`PUBLIC_STORAGE_BUCKET`	—	Public assets bucket name
`S3_ENDPOINT_URL`	`""`	Custom S3 endpoint (leave empty for AWS S3)
`AWS_REGION`	`"eu-west-1"`	AWS region for S3 operations

Observability

Variable	Default	Description
`OTEL_COLLECTOR_ENDPOINT`	`""`	OpenTelemetry collector endpoint
`PROMETHEUS_MULTIPROC_DIR`	`"/tmp"`	Directory for Prometheus multiprocess metrics
`PROM_REMOTE_WRITE_URL`	`""`	Prometheus remote write endpoint
`ENABLE_LLM_OBSERVABILITY`	`"true"`	Enable LLM call tracing in OTEL

Worker Configuration (per deployment)

Variable	Default	Description
`WORKER_SUBSCRIBE`	`"all_but_kb"`	Queue type: `all`, `all_but_kb`, `flow`, `chat`, `kb`
`WORKER_UNSUBSCRIBE_WORKSPACES`	`""`	Comma-separated workspace IDs to exclude (empty = exclude none)
`WORKER_SUBSCRIBE_WORKSPACES`	`""`	Comma-separated workspace IDs to process (empty = all)

Agent Sandbox & Plugins

Variable	Default	Description
`SANDBOX_MANAGER_URL`	`""`	URL of the agent sandbox manager. Plugins execute inside sandboxes, so this also enables the plugin system — empty disables it, silently.
`USE_REMOTE_SANDBOX`	`true`	Route Run Code through the sandbox service rather than executing locally.
`REMOTE_SANDBOX_BACKEND`	`""`	Remote execution backend. `syd` in normal use.
`SANDBOX_BACKEND`	`syd`	Jail implementation: `syd` (syscall + network jail, needs `SYS_PTRACE`) or `minimal` (chroot only).
`LOCAL_SANDBOX_BACKEND`	`deno`	Worker-local fallback: `none`, `deno`, or `subprocess`.
`PLUGIN_CALL_TIMEOUT`	`240.0`	Seconds before a plugin call is abandoned.

LOCAL_SANDBOX_BACKEND=subprocess runs user code in the Worker’s own process tree — with its filesystem, network, and environment, including database credentials. Do not use it in a multi-tenant deployment.

See Agent Sandbox for the deployment model and platform compatibility.

Deployment-Independent Principles

Keep non-sensitive settings in environment config
Keep credentials in secrets only
Keep environment names simple (local, staging, prod)
Do not expose internal-only controls (such as billing internals) in user-facing docs

Noxus supports extensive runtime configuration from the admin portal when the user has global admin permissions. This includes global server settings and auth behavior.

Practical Mapping In Your Stack

VM compose: env_file and explicit env mounts
Helm: env, extraEnv, secrets, plus service-specific secret variants
Terraform stage3: secret/env materialization and namespace-scoped injection

Secrets

Secret handling, provider credentials, and worker secret injection

Workers

Worker pools, task routing, workspace isolation, and autoscaling

Agent Sandbox

Isolated code execution, required for plugins

Storage

Object storage, vector databases, and caching layers

Architecture

PostgreSQL and pgvector requirements, and the runtime topology

Overview

Deployment Options

Networking

Configuration

Security

Operations

Configuration Sources

Environment Variable Layers

Environment Variable Reference

Platform

URLs

Database Configuration

Redis

Object Storage

Observability

Worker Configuration (per deployment)

Agent Sandbox & Plugins

Deployment-Independent Principles

Practical Mapping In Your Stack

Secrets

Workers

Agent Sandbox

Storage

Architecture

​Configuration Sources

​Environment Variable Layers

​Environment Variable Reference

​Platform

​URLs

​Database Configuration

​Redis

​Object Storage

​Observability

​Worker Configuration (per deployment)

​Agent Sandbox & Plugins

​Deployment-Independent Principles

​Practical Mapping In Your Stack

Secrets

Workers

Agent Sandbox

Storage

Architecture

Configuration Sources

Environment Variable Layers

Environment Variable Reference

Platform

URLs

Database Configuration

Redis

Object Storage

Observability

Worker Configuration (per deployment)

Agent Sandbox & Plugins

Deployment-Independent Principles

Practical Mapping In Your Stack