Skip to content

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.

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.

SettingWhy it is required
JWT_SECRETSigns admin session tokens. Unset or left at the dev default, tokens are forgeable.
SESSION_TOKEN_SECRETSigns chat session tokens. Same forgery risk if defaulted.
ERASURE_HASH_PEPPERKeys the irreversible tombstones written by data erasure. The dev default would make erased identifiers brute-forceable.
CREDENTIALS_MASTER_KEYEncrypts stored MCP server credentials at rest.
LLM_API_KEY_MASTER_KEYEncrypts your stored LLM provider API keys at rest.
MCP_AUTH_MASTER_KEYEncrypts stored MCP OAuth / auth material at rest.
DB_PASSWORDMust not be the default postgres.
ADMIN_API_TOKENMust not be the published example value. This token grants full admin permissions.
INITIAL_ADMIN_EMAIL and INITIAL_ADMIN_PASSWORDRequired 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:

Terminal window
# One high-entropy value per required secret
openssl rand -base64 48
Terminal window
# 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>

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.

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.

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.

These are not enforced at startup. They are yours to configure.

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.

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.

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:

SettingEffect
EGRESS_TRUSTED_NETWORKSComma- 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_HTTPtrue 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.

  • All eight boot-required secrets set to unique, high-entropy values.
  • First Owner signed in and changed the password; INITIAL_ADMIN_EMAIL and INITIAL_ADMIN_PASSWORD removed from the environment.
  • ENABLE_TEST_ENDPOINTS unset.
  • DIOSC_DEV_MODE unset.
  • ENABLE_API_DOCS unset.
  • Embed keys scoped to your domains; site origins configured.
  • METRICS_TOKEN set (32+ characters) and your Prometheus job sends it; /api/metrics reachable 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.