Production hardening checklist
DioscHub is self-hosted, so the operational security of the deployment is yours. This page is the checklist. Work through it before you expose the deployment to real users.
DioscHub fails closed: production is the default posture, and the app refuses to start if a security-sensitive setting is left at an insecure default. You do not opt into hardening; you would have to opt out of it. That makes the first half of this list self-enforcing — the app checks it for you at boot. The second half is hardening the boot gate cannot check, so it is on you.
Secrets the app requires to boot
Section titled “Secrets the app requires to boot”Set every value below before starting DioscHub in production. If any is missing or left at its published dev default, the app prints the offending settings and exits — it will not serve traffic in an unsafe state.
| Setting | Why it is required |
|---|---|
JWT_SECRET | Signs admin session tokens. Unset or left at the dev default, tokens are forgeable. |
SESSION_TOKEN_SECRET | Signs chat session tokens. Same forgery risk if defaulted. |
ERASURE_HASH_PEPPER | Keys the irreversible tombstones written by data erasure. The dev default would make erased identifiers brute-forceable. |
CREDENTIALS_MASTER_KEY | Encrypts stored MCP server credentials at rest. |
LLM_API_KEY_MASTER_KEY | Encrypts your stored LLM provider API keys at rest. |
MCP_AUTH_MASTER_KEY | Encrypts stored MCP OAuth / auth material at rest. |
DB_PASSWORD | Must not be the default postgres. |
ADMIN_API_TOKEN | Must not be the published example value. This token grants full admin permissions. |
INITIAL_ADMIN_EMAIL and INITIAL_ADMIN_PASSWORD | Required together on a database with no admin user; without them the app refuses to start. This check runs after the database connects, unlike the others. The password must meet the admin password policy, and the first Owner must change it at first sign-in. Ignored once an admin exists. |
Generate each secret with a real source of entropy, for example:
# One high-entropy value per required secretopenssl rand -base64 48# The shape of a production environment (values are placeholders — generate your own)JWT_SECRET=<48+ random bytes, base64>SESSION_TOKEN_SECRET=<48+ random bytes, base64>ERASURE_HASH_PEPPER=<48+ random bytes, base64>CREDENTIALS_MASTER_KEY=<32+ character key>LLM_API_KEY_MASTER_KEY=<32+ character key>MCP_AUTH_MASTER_KEY=<32+ character key>DB_PASSWORD=<strong, unique database password>ADMIN_API_TOKEN=<unique, high-entropy token>Keep test fixtures off
Section titled “Keep test fixtures off”DioscHub ships internal test-fixture routes under /api/test/* (they can mint tokens and read data)
for its own development. In production they are disabled by default — every /test/* route
returns 404.
Keep the API docs off
Section titled “Keep the API docs off”The hub’s OpenAPI document (/api/docs and /api/docs-json) maps the whole admin API. It is mounted
only in dev mode. Outside dev mode both paths return 404 unless you opt in with
ENABLE_API_DOCS=true; ENABLE_API_DOCS=false turns them off even in dev mode. Leave the variable
unset in production. The internal test-fixture routes are never listed in the document.
Never relax the gate in production
Section titled “Never relax the gate in production”A single flag, DIOSC_DEV_MODE=true, exists so a local dev or CI box can bypass every check above. It
also switches the database into schema-auto-sync mode instead of running migrations.
Hardening the boot gate cannot check
Section titled “Hardening the boot gate cannot check”These are not enforced at startup. They are yours to configure.
Restrict where the widget may be embedded
Section titled “Restrict where the widget may be embedded”The embed key is a public credential by design — it ships in your frontend. Restrict which sites may use it: set each embed key’s allowed domains, and your site’s allowed origins, in the admin portal. An unconfigured key accepts a load from any origin.
Treat origin allowlisting as defence-in-depth, not the primary control. The real boundary is
BYOA: a tool call is authorized by the signed-in user’s forwarded
credential, so an embed used from an unexpected page still cannot act beyond that user’s permissions.
A page with no Origin header (a top-level <script> load) cannot be blocked at this layer at all,
which is why the credential, not the origin, is what bounds the assistant.
Protect the metrics endpoint
Section titled “Protect the metrics endpoint”Prometheus metrics at /api/metrics need a bearer token. Outside dev mode the endpoint answers 404
until you set METRICS_TOKEN (32+ random characters; a shorter one fails the boot gate), and then
401 to any request without Authorization: Bearer <token>. The token is the floor, not the whole
answer: also keep the endpoint reachable only by your monitoring, not the public internet. See
Observability for the Prometheus job and for what the
endpoint exposes.
Restrict outbound destinations
Section titled “Restrict outbound destinations”The hub checks MCP server URLs, webhook sink URLs, and LLM and embedding base URLs against one egress policy (see Models). Link-local and cloud-metadata addresses are always refused. Two settings widen it:
| Setting | Effect |
|---|---|
EGRESS_TRUSTED_NETWORKS | Comma- or space-separated CIDRs, single addresses or hostnames that may be reached on private and loopback ranges. Unset: loopback only outside production, nothing in production. |
EGRESS_ALLOW_HTTP | true or false. In production, plain http is refused outside the trusted networks unless this is true. Outside production, http is allowed by default. |
MCP_TRUSTED_NETWORKS and MCP_ALLOW_HTTP still work as a fallback when the new names are unset. In
production, a self-hosted Ollama or LM Studio on your LAN must be listed in EGRESS_TRUSTED_NETWORKS before
an admin can save or test it. List only the networks you need.
Keep the deployment’s outbound paths narrow
Section titled “Keep the deployment’s outbound paths narrow”DioscHub’s outbound destinations are the ones you configure: your LLM provider, your MCP servers, and your object store if you use one. It does not browse the web or open arbitrary outbound connections on its own. Keep it that way at the network layer — the deployment does not need broad outbound access, and narrowing it bounds the blast radius of any compromise. See the systems DioscHub cannot reach.
Before you go live
Section titled “Before you go live”- All eight boot-required secrets set to unique, high-entropy values.
- First Owner signed in and changed the password;
INITIAL_ADMIN_EMAILandINITIAL_ADMIN_PASSWORDremoved from the environment. -
ENABLE_TEST_ENDPOINTSunset. -
DIOSC_DEV_MODEunset. -
ENABLE_API_DOCSunset. - Embed keys scoped to your domains; site origins configured.
-
METRICS_TOKENset (32+ characters) and your Prometheus job sends it;/api/metricsreachable only by your monitoring. - Outbound network access limited to your LLM provider and MCP servers.
- A test boot completed: the app started without printing a safety violation.