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

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.

Danger

The three master keys are what encrypt your provider and MCP credentials at rest. Set them before production. Without a master key, the corresponding secrets are stored unencrypted. The boot gate refuses to start until all three are present, so the encrypted-at-rest guarantee holds only when they are set. If a feature is unused, a throwaway 32+ character value still satisfies the gate.

Generate each secret with a real source of entropy, for example:

# One high-entropy value per required secret
openssl 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

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.

Danger

Do not set ENABLE_TEST_ENDPOINTS=true in production. Enabling the fixtures is treated as an insecure setting: the boot gate refuses to start. Leave the variable unset. Only a local dev or CI box should ever turn it on.

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.

Danger

Never set DIOSC_DEV_MODE=true in production. It disables the boot gate wholesale — forgeable secrets, the default database password, unencrypted credentials, and the test fixtures all become allowed, and the schema can be altered automatically. Every guarantee on this page is void while it is set. If it is set, unset it and restart.

Hardening the boot gate cannot check

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

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.

Firewall the metrics endpoint

DioscHub exposes Prometheus metrics at /api/metrics, unauthenticated. Put it behind your firewall or network policy so it is reachable only by your monitoring, not the public internet. It is operational telemetry, not a user-facing surface. See Observability for what it exposes.

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

• All eight boot-required secrets set to unique, high-entropy values.
• ENABLE_TEST_ENDPOINTS unset.
• DIOSC_DEV_MODE unset.
• Embed keys scoped to your domains; site origins configured.
• /metrics firewalled.
• Outbound network access limited to your LLM provider and MCP servers.
• A test boot completed: the app started without printing a safety violation.