Self-hostedTalon Studio v1.0.2-beta

Environment Variables

Configure the public URL, secrets, the first admin, the database, and the security switches for your appliance. None of them is required: an empty .env boots.

How it works

Talon Studio is configured entirely through environment variables, read at container start. Set them in the .env beside the compose file, in Helm values, or in your platform's settings, then recreate the container (docker compose up -d) for a change to take effect.

Nothing is required. Every secret you leave unset is generated on first boot, kept in /data/secrets (mode 0600) and reused on every restart; a value you set always wins and is never written there. The ones you will usually set are NEXTAUTH_URL once a proxy is in front, and the first admin's username and email.

URL, secrets and first admin

NEXTAUTH_URL

The URL people use to reach the app, e.g. https://talon.example.com when TLS terminates at a proxy. It is also the base URL deployed detections post SOC notables back to; with it unset, no push webhook is attached and SOC falls back to the manual pull.

AUTH_TRUST_HOST

Trust the host headers a proxy sends. Defaults to true in the image.

AUTH_SECRET

Signs sessions and OAuth state. NEXTAUTH_SECRET is accepted as the same thing. With both unset, one value is generated into /data/secrets/auth_secret and used for both.

TALON_ENCRYPTION_KEY

Encrypts SIEM tokens, AI keys and the other credentials stored at rest. 64 hex characters (or 32 UTF-8 bytes). Generated into /data/secrets/encryption_key if unset. Keep it stable across upgrades and restores.

TALON_ENCRYPTION_KEY_PREVIOUS

Optional comma-separated previous keys, used only to decrypt old ciphertext during a rotation.

TALON_ADMIN_USERNAME

First admin's username. Default talon.

TALON_ADMIN_EMAIL

First admin's email. Default admin@talon.local.

TALON_ADMIN_PASSWORD

Leave unset (recommended) for a random password, printed once in the log and saved to /data/secrets/initial-admin.txt, which must be changed at first sign-in. A well-known value such as talon refuses startup.

TALON_ADMIN_FORCE_PASSWORD_CHANGE

Set true to make a password you set above change at first sign-in too.

The TALON_ADMIN_* variables apply only when the database has no users. They never change or reset an existing account.

Database and pySigma

POSTGRES_PASSWORD

Embedded database password. Generated into /data/secrets/postgres_password if unset. A volume initialised before generation existed keeps the password it was created with (talon), which the image refuses as a default credential.

POSTGRES_USER

Default talon.

POSTGRES_DB

Default detections.

POSTGRES_HOST / POSTGRES_PORT

Default 127.0.0.1 and 5432, inside the container. Never publish the port.

POSTGRES_URL

The full connection string. Built from the variables above when unset. Set it for an external database.

TALON_DISABLE_EMBEDDED_PG

Set true to skip the embedded Postgres and use POSTGRES_URL. The entrypoint waits up to 60s for it and exits if it never answers. A non-loopback host needs sslmode=require, verify-ca or verify-full.

POSTGRES_POOL_MAX

Connections per app process. Default 20.

SIGMA_SERVICE_URL

The pySigma sidecar. Default http://127.0.0.1:8001, built from SIGMA_HOST and SIGMA_PORT.

TALON_DATA_DIR

The data root. Default /data; the repos, content clones, uploads, logs and secrets default to directories under it (GIT_STORAGE_PATH, LOG_DIR, TALON_UPLOADS_DIR, TALON_SECRETS_DIR override them).

Security switches

TALON_STRICT_SECURITY

Set true for any real install. /api/metrics then accepts only the TALON_METRICS_TOKEN bearer, and the startup checks keep their production behaviour even if NODE_ENV is overridden. See Security Hardening for what they refuse.

TALON_ALLOW_INSECURE_DEFAULTS

For a private lab only. Waives the non-critical startup checks — default Postgres credentials, the local metrics token, an external database without TLS. It never waives a placeholder or weak secret or a well-known admin password.

TALON_TRUST_PROXY

Set true when a trusted proxy sets X-Real-IP (read first) and X-Forwarded-For to the client's address and strips the client's own, so rate limits and IP-allowlisted API tokens see the real client IP. IP-allowlisted tokens fail closed without it.

TALON_METRICS_TOKEN

Bearer token for GET /api/metrics, also accepted on /api/health?detailed=1. Unset and not strict, signed-in users can read metrics.

TALON_STRICT_OUTBOUND_URLS

Set true to block outbound integration requests to every private or reserved address. By default loopback and LAN hosts are allowed (on-prem SIEMs are normal) and cloud-metadata endpoints are always blocked.

TALON_ALLOW_PRIVATE_GIT_HOSTS

Set true to allow Git remotes on private or internal hosts.

TALON_ALLOW_PRIVATE_AI_BASE_URLS

Set true to add a self-hosted model on a private or localhost address, such as Ollama on host.docker.internal. The image rejects those otherwise.

TALON_ALLOW_INSECURE_AI_TLS

Set true only for an approved internal AI endpoint with invalid TLS.

NODE_EXTRA_CA_CERTS

Path to a mounted CA bundle, for outbound HTTPS to services behind a corporate CA.

Logs, sessions and metrics

LOG_LEVEL

debug, info (default), warn or error.

LOG_FORMAT

text (default) or json, one object per line, for a log aggregator.

LOG_RETENTION_DAYS

Days to keep rotated log files in /data/logs. Default 14.

LOG_MAX_FILE_MB

Size at which the log file rotates. Default 50. DISABLE_LOG_FILE=true turns the file off.

SESSION_MAX_AGE_DAYS

Absolute session lifetime. Default 7.

AUDIT_LOG_RETENTION_DAYS

How long audit-log rows are kept before the startup purge removes them. Default 365.

Content, AI and licence

DISABLE_DETECTION_CONTENT_SYNC

Set true to stop the content library syncing from its public Git sources (SigmaHQ, Splunk Security Content, Atomic Red Team and others). It runs at startup and then hourly (CONTENT_SYNC_INTERVAL_MS).

SIGMA_RULES_REPO

Point a content source at an internal mirror. Also SPLUNK_SECURITY_CONTENT_REPO, AZURE_SENTINEL_REPO, CHRONICLE_DETECTION_RULES_REPO and FALCONFRIDAY_REPO.

TALON_DISABLE_UPDATE_CHECK

Set true to stop the in-app check for a newer release. While the app is open it asks https://www.talonlabs.dev/releases.json about once an hour, on any key, reads a newer release's notes from https://www.talonlabs.dev/changelog/studio.md, and sends nothing about the install.

TALON_LLM_GATEWAY_URL

Optional OpenAI-compatible AI gateway base URL, with TALON_LLM_GATEWAY_API_KEY.

ANTHROPIC_API_KEY

Optional fallback provider key, as are OPENAI_API_KEY and XAI_API_KEY. AI providers are normally configured per organisation in the UI.

TALON_LICENSE_KEY

A signed talstu_… key — your Community key, or an Enterprise key — applied at startup once the first admin exists. Safe across restarts; meant for provisioning automation — an admin can paste the same key in the License dialog instead. With no key either way, the instance shows only the key screen. Helm: secrets.licenseKey.

TALON_LICENSE_API_URL

Talon Labs' licence API, https://www.talonlabs.dev/api/license in the release compose file and the Helm chart (config.licenseApiUrl). Only an Enterprise key calls it — to activate, check in daily and release; a Community key never does. Unset or empty, the appliance makes no licence call, and an Enterprise key pasted then is stored as provisional until one can be made. Making no call to Talon Labs at all also needs TALON_DISABLE_UPDATE_CHECK=true.

There is no variable that changes the Community Edition limits, bypasses the licence check, or substitutes the key it verifies against. TALON_LICENSE_PUBLIC_KEY, SELF_HOSTED_COMMUNITY_MAX_* and SELF_HOSTED_TEAM_MAX_* are no longer read; remove them if an old .env carries them. The background loops and the AI assistant have further tuning variables, all with safe defaults.

An example .env

A .env for an install behind a TLS proxy:

.env

TALON_STUDIO_IMAGE=ghcr.io/talon-labs-detection-platform/talon-studio:v1.0.2-beta

NEXTAUTH_URL=https://talon.example.com

TALON_TRUST_PROXY=true

# first admin: leave TALON_ADMIN_PASSWORD unset for a generated one

TALON_ADMIN_USERNAME=admin

TALON_ADMIN_EMAIL=admin@example.com

TALON_STRICT_SECURITY=true

TALON_METRICS_TOKEN=<openssl rand -hex 32>

# secrets: omit to have them generated into /data/secrets

# AUTH_SECRET=<openssl rand -hex 32>

# TALON_ENCRYPTION_KEY=<openssl rand -hex 32>

Rotating the encryption key

Set the new key as TALON_ENCRYPTION_KEY and move the old one into TALON_ENCRYPTION_KEY_PREVIOUS. New writes use the new key and old ciphertext still decrypts. Backup & Restore has the full sequence.

No escape hatch for credentials

A placeholder, weak or missing secret, or a well-known admin password, refuses startup whatever TALON_ALLOW_INSECURE_DEFAULTS or NEXTAUTH_URL say.