- 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
Environment Variable Reference
Platform
Scripts
Admin Python scripts bound to platform events (middleware and hooks), on-prem only (see Scripts). They need a Linux kernel with Landlock (5.13 or later; 6.7 or later to refuse the network) in the backend and worker containers.
|
EXTENSIONS_PYTHON | "" | Interpreter of a scripts environment you maintain; the image’s own is used when empty |
| EXTENSIONS_MAX_FILE_BYTES | "67108864" | Largest stored file a file.uploaded hook downloads as event.file_path, and largest test file; an upload middleware always gets the whole file |
| WORKER_EXTENSIONS_CONCURRENCY | "4" | Hook jobs a worker pod runs at once |
Disk high-watermark
On a host where the platform shares one disk (docker-compose, VM), the backend and workers watch free space and refuse new work once it is critical (HTTP 507, worker tasks re-queued until space is freed). The Platform Status page and the in-app storage dialog show the level and the thresholds in force.
The percentage and the absolute floor are combined so that a level trips at
whichever point comes later as the disk fills, i.e. the smaller free-space
figure of the two. GB are decimal (10^9 bytes), the unit the UI shows.
The critical level follows the same rule with
STORAGE_CRITICAL_PERCENT and
STORAGE_CRITICAL_FREE_GB.
Private network access
SetALLOWED_PRIVATE_CIDRS on the backend and every worker to a comma-separated
CIDR allowlist, for example:
env.ALLOWED_PRIVATE_CIDRS in values.yaml. For VM deployments,
add the variable to /env.vm or /env.extra, not to /local/env.vm, which is
regenerated from /env.vm on every start. For Docker Compose, pass it
through the backend and worker services’ environment sections. Restart backend
and worker processes after changing it;
new sandboxes then use the updated policy. Existing persistent sandboxes retain
their original policy, including across stop and resume.
For remote sandboxes this requires the Syd provider (sandbox.jail: syd in Helm).
The minimal provider does not apply the per-sandbox CIDR allowlist;
the Helm minimal NetworkPolicy continues to block private networks.
The default is empty: private destinations remain blocked. This is one deployment-wide
policy, with no database setting, UI control, or workspace override. It applies to
API Request, scraper, crawler and file downloads, Run Code through Deno or Syd,
browser playbooks, vault integrations, and MCP URL checks. The existing MCP
“Allow private-IP MCP servers” toggle remains available for compatibility.
With that toggle off, MCP URL checks still allow destinations in
ALLOWED_PRIVATE_CIDRS; no separate MCP environment variable is needed.
Turning it on preserves the existing broader MCP bypass, including addresses
outside this allowlist. Leave it off to apply the CIDR policy to MCP.
Only the portions of the listed CIDRs within RFC1918 (10/8, 172.16/12,
192.168/16) and IPv6 ULA (fc00::/7) are allowed. IPv4-mapped IPv6 destinations
are checked against their IPv4 address. Loopback, link-local and metadata,
unspecified, multicast, and reserved destinations cannot be allowed by this variable,
even if listed or covered by a broad entry. The AWS IPv6 metadata endpoint
fd00:ec2::254 is also excluded from ULA allowlists. Malformed entries fail startup with an
ALLOWED_PRIVATE_CIDRS validation error. Host bits are normalized to the network.
Startup logs show the effective networks after protected ranges are removed.
The worker and backend pass the policy in authenticated sandbox creation requests;
Syd applies it to outbound connections inside that sandbox. You do not need to
configure SYD_ALLOWED_CIDRS for this feature. Existing operator-defined Syd
rules, resolver access, and managed browser ports retain their existing behavior.
A sandbox with a non-empty allowlist, from this variable or SYD_ALLOWED_CIDRS,
may also bind a socket to 0.0.0.0 on an ephemeral port before connecting, as
Microsoft’s ODBC Driver 18 for SQL Server does. Without an allowlist, Syd rewrites
that bind to loopback and such a client reports a login timeout.
The sandbox manager API key is an operator credential: its holder can request
any eligible private CIDRs, with no additional deployment-level CIDR ceiling
enforced by the manager.
This setting permits a destination through SSRF checks. It does not provide a
network route or resolve internal DNS names; both must work from the deployment.
These were separate causes of connectivity failures at Frulact.
Environment-backed workspace secrets
On on-prem deployments a workspace secret can take its value from an environment variable of the backend and worker processes instead of storing it on the platform (source Environment in the variable form). Two guard rails apply:- Names the platform itself is configured with are refused, on save and at run
time: every variable listed on this page, the secrets and internal configuration
files, and the credentials the cloud SDKs and model providers read (
AWS_*,AZURE_*,GOOGLE_APPLICATION_*,OPENAI_*,ANTHROPIC_*and similar). Expose a value for workspaces under a name of your own, for exampleCUSTOMER_API_KEY. - A platform administrator can turn the source off for the whole deployment with Allow environment-backed secrets in Settings › System › Security. It is on by default. When it is off, new secrets cannot use the source, the variable form says why the option is unavailable, and secrets that already use it fail to resolve with a clear error until they are switched to another source or the setting is turned back on. The setting is stored in the database, so it needs no restart.
URLs
Database Configuration
Redis
Object Storage
Observability
Worker Configuration (per deployment)
Agent Sandbox & Plugins
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_fileand 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