Project Overview

Configuration

The backend is configured through Spring Boot properties, the Studio through environment variables that are mostly baked in at build time. Neither repository file carries real credentials: they come from the deployment (see Configuration and Secrets) or, locally, from git-ignored files (Development Setup).

How the Backend Reads Its Configuration

Spring Boot merges these sources; a later one wins:

  1. application.properties on the classpath (backend/src/main/resources/) — defaults for a local run, with placeholders (change-me) where a credential belongs.

  2. /config/application.properties — rendered by the Helm chart’s ConfigMap: the environment’s domain, namespace and version, the MongoDB database name, the MCP server URLs, the conversation-data index patterns and the test-suite URLs.

  3. /config/application-default.properties — the environment’s own settings and credentials, mounted from Azure Key Vault. It is a profile-specific file for the default profile, which is the active profile in a deployment, so it overrides both files above.

  4. Environment variables set by the Deployment, for example PROMETHIST_TESTING_BRIDGESECRETTOKEN from the release’s Kubernetes secret.

Locally, application-local.properties takes the place of the mounted files when the local profile is active. backend/src/test/resources/application.properties replaces the main file entirely in tests.

Backend Properties

Server and Infrastructure

Property Default Meaning

server.port

9310

HTTP port of the REST API, the MCP endpoint and Actuator.

server.max-http-request-header-size

12KB

Header size limit of the HTTP server.

app.domain, app.namespace, app.version

— (set by Helm)

The environment’s host domain and Kubernetes namespace. They derive the engine URL and the Studio URL used in invitation emails (see Talking to the Engine). Without a domain the derived URL is http://localhost:3000.

spring.mongodb.uri, spring.mongodb.database

mongodb://localhost:9417/promethist-platform, promethist-platform

The database shared with the engine. The Helm ConfigMap sets the database name to the release name.

spring.mongodb.representation.uuid

standard

UUIDs are stored as standard BSON binary subtype 4, the representation the engine uses as well.

spring.elasticsearch.uris, spring.elasticsearch.username, spring.elasticsearch.password

Spring Boot defaults

The Elasticsearch cluster of the knowledge vector store and the conversation-data views.

spring.ai.vectorstore.elasticsearch.index-name

Spring AI default

Index of the knowledge chunks; must be the index the engine searches.

spring.security.oauth2.resourceserver.jwt.issuer-uri

https://keycloak.promethist.ai/realms/platform

Issuer of the Keycloak access tokens the REST API and the assistant accept. Also the realm the identity-provider check probes.

management.endpoints.web.exposure.include

health,prometheus,metrics

Actuator endpoints exposed over HTTP: health and metrics. prometheus needs the Micrometer Prometheus registry, which is not on the backend’s classpath, so there is no /actuator/prometheus (Observability).

management.health.elasticsearch.enabled, management.health.neo4j.enabled

false

Keep Elasticsearch, which is optional, out of the health status, and Neo4j, whose driver the Spring Data Neo4j starter puts on the classpath although the platform has no Neo4j database.

Shared Library Settings

These are bound by classes of promethist-common.

Property Default Meaning

promethist.acl-service.enabled

true

Enables AclService, which every permission check uses. It must stay on.

promethist.storage.type, .ref, .endpoint, .region, .identity, .secret

Azure, …

Where uploaded logos and media are written. Azure (blob storage) and File (a local directory named by ref) are supported.

promethist.mailing.sender, .api-key, .domain, .base-url

noreply@elysai.com, —, mg.elysai.com, Mailgun EU API

Mailgun account for invitation emails. Without an API key no email is sent.

promethist.mailing.templates.inviteTenantUser, promethist.mailing.templates.inviteProjectUser

promethist-platform: tenant invite, promethist-platform: project invite

Names of the stored Mailgun templates the invitations are rendered with. The wording of the emails lives in Mailgun, not in this repository.

Video Re-encoding

Property Default Meaning

promethist.video-transcoding.enabled

true

Re-encodes uploaded interactive-content videos (Re-encoding of Uploaded Videos). Without ffmpeg and ffprobe the backend logs a warning at startup and serves uploads as uploaded, as with false. The test resources set it to false, and so do issue environments (the chart value app.videoTranscoding).

promethist.video-transcoding.ffmpeg, promethist.video-transcoding.ffprobe

ffmpeg, ffprobe

The two executables, found on the PATH unless given with their path.

promethist.video-transcoding.timeout

30m

How long one encoding may run before ffmpeg is killed and the original kept.

promethist.video-transcoding.memory-limit

768MB

The memory ffmpeg and ffprobe may allocate, set with prlimit (RLIMIT_DATA): an encoding that needs more fails and keeps the original. Without prlimit, as on macOS, nothing is capped.

How a video is encoded — codec, bitrate, size — is not configurable: the settings are constants of VideoTranscoder, versioned by ENCODE_VERSION.

AI

Property Default Meaning

promethist.ai.azure-open-ai.api-key, .endpoint, .service-version

—, promethist-common defaults

Azure OpenAI resource of the AI Assistant, its nested model calls and the web search.

promethist.ai.open-ai.api-key

—

OpenAI key for knowledge embeddings and, by default, transcription.

promethist.ai.transcription.provider, .model, .language, .vocabulary, .max-bytes

OPEN_AI, gpt-transcribe, unset, product names, 25 MB

Speech-to-text of the assistant’s voice input. model is a model id on OpenAI and a deployment name on Azure (AZURE_OPEN_AI). Leave language unset unless every user speaks one language.

promethist.ai.web-search.model, .reasoning-effort, .api-version, .max-output-tokens, .max-sources, .timeout-seconds

gpt-5.5, medium, preview, 16000, 15, 300

The assistant’s webSearch tool, answered by one Responses API call with the provider’s web search.

promethist.azure.documentIntelligence.endpoint, promethist.azure.documentIntelligence.api-key

—

Azure AI Document Intelligence for knowledge files.

promethist.parser.max-chunk-size

2000

Upper bound, in characters, of a chunk built from a Document Intelligence layout.

promethist.platform.assistant.tenant-creation-enabled, promethist.platform.assistant.project-creation-enabled

false

Register the assistant tools that create accounts and projects.

promethist.assistant.streaming.enabled, .batch-window-ms, .batch-max-chunks

true, 50, 64

Streaming of the assistant’s replies: chunks are batched for at most the window or the chunk count.

promethist.chat-attachments.max-files, .max-file-size-bytes, .max-total-raw-bytes, .allowed-extensions

5, 10 MB, 25 MB, documents, images and spreadsheets

Limits of the files a user attaches to an assistant message. The Socket.IO frame size is derived from the total.

promethist.socket-io.enabled, promethist.socket-io.port

true, 9311

The assistant’s Socket.IO server.

The chat model itself is not configurable: LLMService.CHAT_MODEL names the Azure deployment and LLMService.REASONING_EFFORT its reasoning effort (see The Model).

Hosted MCP Server

Property Default Meaning

promethist.mcp.issuer

required

The authorization server (the Studio’s origin). Tokens must carry it as iss.

promethist.mcp.jwks-uri

required

Where the signing keys are published: {issuer}/oauth/jwks.

promethist.mcp.audience

required

The MCP endpoint’s own URL, https://{host}/api/v1/mcp. Tokens must carry it in aud.

promethist.mcp.resource-metadata-url

required

The protected-resource metadata URL announced in the 401 challenge.

promethist.mcp.web-url

required

Base URL of the Studio for the webUrl links in tool results.

promethist.mcp.engine-url

required

The engine test_agent talks to.

promethist.mcp.data-views.turns, promethist.mcp.data-views.llm-logs

*-turn-default-*, *-llmlog-default-*

Elasticsearch index patterns of the conversation-data tools. Deployments set them per namespace, because preview shares production’s cluster.

promethist.mcp.bridge.base-url, .engine-url, .relay-url, .variable-group, .tester-realtime-configuration-id

EU production values

What the staff test-harness tools write into bridge configurations.

The six required URLs have no defaults on purpose. A deployment that misses one fails at startup instead of silently trusting another environment’s tokens.

Test Suites

Property Default Meaning

promethist.testing.bridge-url

http://localhost:9013

The bridge’s REST API. Blank disables test suites.

promethist.testing.bridge-secret-token

—

Token sent to the bridge. Delivered as an environment variable from a Kubernetes secret, never through the ConfigMap.

promethist.testing.engine-url

blank (derived)

The engine the tested agents run on.

promethist.testing.engine-basic-identity

—

HTTP Basic credentials of the engine’s test identity, which test_agent uses for projects that admit only signed-in users. Delivered like the bridge token. Expected is the base64 credential, with or without Basic `. Surrounding quotes, a `NAME= or YAML-style name: ` prefix and a whole `Authorization: header are read past, and a raw username:secret is base64-encoded by the backend. At startup the backend logs whether the identity is usable, malformed or not configured, and nothing of the value itself.

promethist.testing.max-parallelism, .grace-seconds, .device-delay-millis, .trigger-timeout-seconds, .claim-stale-seconds

5, 120, 5000, 30, 120

Run tuning: how many conversations of a run the bridge executes in parallel; how long past its own timeout a conversation may run before it reads as timed out (and how long a triggered suite may show no conversation before it reads as failed); the bridge’s device start delay; the timeout of each bridge request; and after how long a "this suite is starting" claim is considered stale.

Billing and Scheduling

Property Default Meaning

stripe.apikey, stripe.webhookSecret

placeholders

Stripe API key and the signing secret of the webhook.

stripe.region

placeholder

Region tag of this deployment. Subscriptions are created with it in their metadata, and webhook events of other regions' subscriptions are ignored.

promethist.scheduling.enabled

false in the committed file

Master switch of the scheduled jobs. With it on, each job can still be switched off: promethist.scheduling.createEdrTasks, .processEdr, .reportUsages, .clearInvitations (all on by default). See The Usage Pipeline.

Prices are not configuration: they come from the package collection (Accounts and Subscriptions).

Accounts and Secrets

Property Default Meaning

promethist.tenant-seeding.enabled, promethist.tenant-seeding.source-project-ref

false, empty

When enabled, a new account gets a copy of the project with this ref instead of an empty default project.

promethist.vault.enable, promethist.vault.impl

true, empty

The staff-only vault endpoint and its implementation: empty (always "not found") or azure.

promethist.vault.azure.name, .tenant-id, .client-id, .client-secret

placeholders

The Key Vault the azure implementation reads.

LIVE_AVATAR_API_URL

https://api.liveavatar.com

LiveAvatar API used for live-avatar preview images.

Studio Frontend

The Studio reads process.env on the server and in the browser. Variables prefixed NEXT_PUBLIC_ are inlined into the browser bundle at build time, which is why the pipeline builds a separate frontend image per environment and region.

Variable Meaning

AUTH_URL, NEXTAUTH_URL

The Studio’s own URL, for NextAuth callbacks. NextAuth reads AUTH_URL first; the NEXTAUTH_ names are its backwards-compatible aliases.

AUTH_SECRET, NEXTAUTH_SECRET

Secret that encrypts the NextAuth session cookie (same precedence).

AUTH_KEYCLOAK_ID, AUTH_KEYCLOAK_SECRET, AUTH_KEYCLOAK_ISSUER

The Keycloak client (platform) and realm URL the Studio signs users in with.

NEXT_PUBLIC_URL

The public URL of the Studio. It also decides whether the Studio considers itself local, preview or production, and the EU or US region.

NEXT_PUBLIC_OVERRIDE_PLATFORM_URL

Base URL of the backend REST API for browser and server calls (default: the EU preview).

NEXT_OVERRIDE_PLATFORM_URL

Server-only override of the backend URL used by the Studio’s proxy routes.

NEXT_PUBLIC_OVERRIDE_PLATFORM_SOCKET_URL

Base URL of the assistant’s Socket.IO server. Defaults to http://localhost:9311 in development and to NEXT_PUBLIC_URL otherwise.

MCP_OAUTH_ISSUER

The issuer of the MCP OAuth tokens — the Studio’s own origin. Must equal the backend’s promethist.mcp.issuer.

MCP_RESOURCE

The MCP endpoint the tokens are issued for. Must equal the backend’s promethist.mcp.audience.

MCP_OAUTH_PRIVATE_JWK

The RSA private key (JWK, with a kid) that signs the MCP tokens. One key per environment; there is deliberately no fallback.

NEXT_PUBLIC_ENABLE_BILLING, NEXT_PUBLIC_FORCE_SUBSCRIPTION_CHECKS, NEXT_PUBLIC_MARKER_IO_ENABLED

Development and feedback switches, see Feature Flags for Local Work.