Configuration readiness

The server checks its deployment settings at startup, under the production profile. GET /api/admin/configuration-readiness returns those facts and the checks that need runtime state. The readiness card of the instance admin overview shows them. The endpoint requires the app_admin authority. It is available only after the checks that can prevent startup pass. Diagnostics never contain configured values.

The chart sets each setting from your values and the release Secret (Configuration reference).

Each fact has a stable id, the configuration subject, the runtime roles, a requirement, a status, an explanation and a link to its section on this page. The requirement is REQUIRED, RECOMMENDED, or OPTIONAL.

Status	Meaning
SATISFIED	The check passed.
ACTION_REQUIRED	The check failed. A required deployment fact with this status prevents startup.
NOT_CONFIGURED	An optional setting is absent.
NOT_APPLICABLE	The check does not apply to this server, for example an agent check without sandbox.enabled.

Fact id	Requirement	Section
runtime.roles	Required	Server role
database.url, database.username, database.password	Required	Database
security.credential-encryption, security.value-encryption	Required	Credential encryption
external.base-url, external.api-origin	Required	External URL
webhook.shared-secret, webhook.routing-secret	Required	Webhooks
auth.state-cookie-key, auth.login-provider	Required	Login
llm.proxy-egress	Required with sandbox.enabled	LLM proxy
agent.image-contract	Required with sandbox.enabled	Agent image
notification.email	Optional	Email

Server role

runtime.roles checks that the server role is on. The chart always turns it on. sandbox.enabled turns on reviews, conversation turns and their sandboxes (Reviews and conversation turns).

Database

database.url checks that DATABASE_URL is a PostgreSQL URL. The production profile adds the jdbc: prefix. database.username and database.password check that both values are not empty. Spring Boot and Liquibase check the connection and the migration separately. An options parameter in DATABASE_URL replaces the 10-second lock wait limit of the server's connections.

A remote database requires TLS, and production startup refuses a plaintext remote connection. The chart always connects with sslmode=verify-full, which encrypts the connection and verifies the server identity.

Credential encryption

CAUTION: Preserve encryption keys

Do not change the general encryption key on an existing installation. Rotate the credential key with the documented online procedure.

security.credential-encryption checks HEPHAESTUS_SECURITY_CREDENTIAL_ENCRYPTION_KEY, which encrypts stored integration credentials. security.value-encryption checks HEPHAESTUS_SECURITY_ENCRYPTION_KEY, which seals JWT signing keys and other encrypted values. Each key must be exactly 32 printable, non-space ASCII characters. Keep both keys with the backup set, in separate storage with separate credentials (Keep the required keys outside the cluster).

External URL

external.base-url checks hephaestus.host-url, and external.api-origin checks hephaestus.auth.issuer. Each must be a root HTTPS origin, with no credentials, query, fragment, or path other than /. Provider webhooks and the Slack callback use the issuer. The chart sets both from host.

Webhooks

webhook.shared-secret checks WEBHOOK_SECRET. It needs at least 32 printable, non-space ASCII characters. Never reuse another application key.

webhook.routing-secret checks WEBHOOK_ROUTING_SECRET, also on a deployment without GitLab. GitLab group hooks and Outline subscriptions use it. It needs at least 32 printable, non-space ASCII characters, and must differ from WEBHOOK_SECRET.

Login

auth.state-cookie-key checks HEPHAESTUS_AUTH_STATE_COOKIE_KEY, a Base64-encoded 32-byte key that seals the OAuth state. auth.login-provider checks that at least one GitHub or GitLab sign-in provider is enabled in the provider catalog of the instance. Environment provider entries only seed the catalog. Slack and Outline only link accounts, so they do not satisfy this check.

Recent sign-in for sensitive actions

These actions require a sign-in from the last few minutes:

• Change an account's role.
• Force an account out of all its sessions.
• View as a user.
• Change a login provider.
• Register an LLM connection.
• Link an identity.

That window is 5 minutes. The confirmation uses a provider that is already connected to the account. It is not multi-factor authentication: enforce MFA at the provider. The server does not replay a refused action, so the user submits it again after the confirmation.

Session deadlines

The access cookie lasts 24 hours. While a tab is active, the browser renews it about every hour. After the cookie expires, the user must sign in. A session ends after 7 days, whatever the activity. Renewal never moves a session past that deadline. Revocation and account suspension deny access before either deadline.

Tokens stay in HttpOnly, Secure, host-only, SameSite=Lax cookies, never in local storage. An account can hold parallel sessions, one for each browser or installed client. An instance admin can end every session of one account with Force sign out, or block the account. To end every session on the instance, see End every session on the instance. For shared computers or sensitive deployments, require MFA at the identity provider.

LLM proxy

llm.proxy-egress checks that HEPHAESTUS_LLM_EGRESS_ALLOW_LOOPBACK is false on a server with sandbox.enabled. Provider credentials and models are runtime settings in the database, not deployment settings (AI providers).

Agent image

agent.image-contract checks, on a server with sandbox.enabled, that HEPHAESTUS_AGENT_IMAGE_REQUIRE_DIGEST is on and that HEPHAESTUS_AGENT_IMAGE_REFERENCE is pinned by its SHA-256 digest. The chart sets both from the release (Release image lock).

Email

Email is optional. notification.email is NOT_CONFIGURED until spring.mail.host names a relay. It is ACTION_REQUIRED if a relay is set but hephaestus.email.from is blank. Every notification is then withheld and recorded as NOT_CONFIGURED. This fact never prevents startup.

Integration settings → Email gives the configuration and the test. Before you turn on email, complete the processing review in the processor checklist.