CALM Hub
CALM Hub is the central artifact store and API server for the CALM ecosystem. It provides a versioned, queryable registry for CALM architecture models, patterns, compliance controls, standards, and related assets — enabling teams to publish, discover, and share architecture knowledge across an organisation.
CALM Hub exposes a RESTful HTTP API that powers both the CALM Hub UI visual interface and programmatic integrations such as the MCP endpoint.
Features
| Feature | Description |
|---|---|
| Namespace-scoped artefact store | Architectures, patterns, flows, standards, interfaces, ADRs, and controls organised under user-defined namespaces |
| Versioned resources | Every artefact carries an incrementing version history; compare any two versions via the timeline UI |
| Multiple storage backends | MongoDB (production), NitriteDB embedded (standalone/development), or a baked-in read-only database (static distribution) |
| Conventions | Versioned tool settings, such as a C4 mapping, checked against the schema of their type. A namespace names a default, and child namespaces inherit it. See Conventions |
| Read-only mode | Serves a pre-seeded, immutable CALM dataset with no external database dependency; mutating requests are rejected with HTTP 405 |
| Scope-based access control | Fine-grained OAuth2 scopes (e.g. architectures:read, architectures:all, namespace:admin) enforced per endpoint |
| OpenAPI / Swagger UI | Auto-generated API documentation always available at /q/swagger-ui |
| MCP server | Experimental Model Context Protocol endpoint at /mcp for AI-agent integrations |
| Multi-arch container images | Pre-built linux/amd64 and linux/arm64 images for all four variants |
Supported Runtimes
CALM Hub is published as four container image variants, each combining a JVM runtime (JVM vs. GraalVM native binary) with a storage backend (MongoDB vs. NitriteDB read-only).
JVM vs. Native
| JVM | Native | |
|---|---|---|
| Startup time | ~3 – 5 s | < 0.5 s |
| Memory footprint | ~200 MB heap | ~50 – 80 MB RSS |
| Build time | ~30 s | 5 – 15 min (GraalVM Mandrel) |
| Debuggability | Full Java tooling | Limited (no JVM agents) |
| Platform | Any JDK 21 host | Compiled per arch (amd64, arm64) |
Storage Modes
| Mode | Backend | External dependency | Mutating writes |
|---|---|---|---|
| MongoDB (default) | External MongoDB 5.0+ | Yes — QUARKUS_MONGODB_CONNECTION_STRING | ✅ Yes |
| Standalone (NitriteDB) | Embedded file-based DB | No | ✅ Yes (file persisted at CALM_STANDALONE_DATA_DIRECTORY) |
| Read-only | Pre-seeded NitriteDB | No | ❌ No — HTTP 405 for POST/PUT/DELETE/PATCH, except on a readOnly extension route |
GitHub (calm.database.mode=github) | Cloned GitHub repositories | Yes — GitHub API | ❌ No — read-only from Git |
In GitHub mode, CALM Hub classifies .json and .md files in each configured repository from content signals (moments or $schema) and from parent directory names (architectures/, patterns/, standards/ or standard-nodes/, flows/, interfaces/, controls/, adrs/, timelines/, decorators/). See GitHub Storage Mode for configuration, sync, versions and access control.
The Four Image Variants
| Tag | Runtime | Storage | Use case |
|---|---|---|---|
latest | JVM | MongoDB | Standard production deployment |
latest-native | GraalVM native | MongoDB | Low-latency / resource-constrained production |
latest-read-only-static | JVM | Read-only NitriteDB | Fast demo/CI; ships the full CALM schema set |
latest-read-only-native | GraalVM native | Read-only NitriteDB | Minimal footprint, self-contained, fast startup |
Read-Only Mode
Overview
Read-only mode lets you run CALM Hub as a completely self-contained, stateless container — no database to provision, no credentials to manage. The CALM schema data is baked directly into the image.
When CALM_READONLY=true is set:
ReadOnlyRequestFilterintercepts every inbound request before routing. Any HTTP method that mutates state (POST,PUT,DELETE,PATCH) is rejected immediately withHTTP 405 Method Not Allowedand aAllow: GET, HEAD, OPTIONSresponse header. The extension proxy, form and chat paths are the exception: the filter lets them through, and CALM Hub then allows a method other thanGETonly on a route that the manifest marksreadOnly(see Calling an extension).- NitriteDB is opened with
.readOnly(true).autoCommit(false), preventing any accidental writes to the embedded database file.
The MCP endpoint (/mcp) does not go through that filter. Each MCP tool that changes data returns a tool error on a read-only Hub. Hub does this check before the permission check, so a caller without the scope also gets the read-only error. A tool that needs only a read scope still runs, and so do the extension commands that a read-only Hub can run. tools/list does not show the tools that change data, and a read-only Hub registers no extension command for a write route. This applies to all users of a read-only Hub. It is not a filter by user or scope, which Hub does not do (see ADR 0014).
# Run the read-only JVM image — no external dependencies needed
docker run --rm -p 8080:8080 finos/calm-hub:latest-read-only-static
# Test that mutations are blocked
curl -s -o /dev/null -w "%{http_code}" \
-X POST http://localhost:8080/calm/namespaces \
-H 'Content-Type: application/json' -d '{"name":"test"}'
# → 405
The read-only images serve the $id of each name-based document under https://hub.calm.finos.org, because the seeded documents belong to that Hub. To use a different base, add -e CALM_HUB_BASE_URL=<url> to docker run.
How the Read-Only Data Image Layer Works
The read-only images use a two-stage Docker build to pre-seed the embedded NitriteDB with the full CALM schema dataset at build time:
Stage 1 — seed (JVM, writable)
FROM ubi8/openjdk-21 (static) or ubi9/openjdk-21 (native)
COPY quarkus-app/ + released meta-schemas (npm copy) + controls/ + interfaces/
RUN boot Quarkus in standalone (writable) mode
→ init script POSTs all schemas and controls into NitriteDB
→ graceful SIGTERM flushes and commits the database
→ calmSchemas.db is now ~290–450 KB of real data
Stage 2 — runtime (minimal base image)
COPY --from=seed /data/calmSchemas.db ← baked as an image layer
chmod 0444 ← immutable at filesystem level
ENV CALM_READONLY=true
ENV QUARKUS_PROFILE=standalone
ENV CALM_HUB_BASE_URL=https://hub.calm.finos.org
The resulting image carries the seeded database as a read-only filesystem layer. At runtime the process opens the file in read-only mode, serves the pre-loaded content, and rejects all write requests.
Why the native read-only image uses a JVM for seeding: GraalVM native binaries compiled from NitriteDB cannot reliably write (commit) the H2 MVStore backing file due to Java serialisation requirements that are not fully supported in native mode. The JVM seed stage produces a database file that the native binary can then read correctly (via registered serialisation metadata). The native runtime is only ever used for reads in the read-only image.
UI Customization
An operator can brand CALM Hub UI, choose what its menus show and add deployment-specific information, with configuration only. Each calm.ui.* property can also be set as an environment variable. If you set none of them, CALM Hub UI uses the CALM name, logo and colours.
| Item | Where it shows | Properties |
|---|---|---|
| Organisation and application names | Header, home page, browser tab, search boxes | calm.ui.branding.organisation-name, calm.ui.branding.application-name |
| Logo | Header and home page, in place of the CALM logo | calm.ui.branding.logo.light, calm.ui.branding.logo.dark |
| Brand colour | Links, active tabs and rows, filled badges, focus rings | calm.ui.branding.colour, calm.ui.branding.colour-dark |
| Menu layout | menu (default): the hamburger menu. sidebar: a collapsible menu at the left of each page on a wide screen. The browser remembers the collapse choice | calm.ui.navigation.layout |
| Built-in sections | Explore sidebar, home page | calm.ui.navigation.show-namespaces, calm.ui.navigation.show-control-domains |
| Extensions heading | Menu and home page | calm.ui.navigation.extensions-heading |
| Start page | The page that opens at the root URL | calm.ui.navigation.start-page |
| Environment pill | Header, on every page | calm.ui.environment.name, calm.ui.environment.colour |
| Signed-in identity | Menu | calm.ui.identity.enabled, calm.ui.identity.show-roles |
| Values and links | Menu | calm.ui.items[n].label, .value, .url |
CALM_UI_BRANDING_ORGANISATION_NAME="Northstar Financial"
CALM_UI_BRANDING_APPLICATION_NAME="Architecture Hub"
CALM_UI_BRANDING_COLOUR=#0f766e # #rrggbb; COLOUR_DARK sets another colour for the dark theme
CALM_UI_BRANDING_LOGO_LIGHT=/config/branding/logo.svg
CALM_UI_BRANDING_LOGO_DARK=/config/branding/logo-dark.svg
CALM_UI_NAVIGATION_LAYOUT=sidebar # menu | sidebar
CALM_UI_NAVIGATION_SHOW_CONTROL_DOMAINS=false
CALM_UI_NAVIGATION_START_PAGE=/extensions/release-tracker/releases
- Names can have at most 64 characters, and the extensions heading at most 40.
- CALM Hub reads each logo from a local file one time, at start up. It does not get images from other servers. A logo is a PNG, JPEG, WebP or SVG file of at most 256 KiB. The file extension must agree with the content. A PNG, JPEG or WebP image can be at most 2048 pixels on each side. An SVG must not have scripts, event attributes, or links to other files or pages. A dark logo needs a light logo. Without a dark logo, the dark theme shows the light logo on a white plate. If the browser cannot show a logo, the UI shows the names, or the CALM logo if you set no name.
- The UI makes the brand colour darker or lighter where it must, so that text in it has a contrast of 4.5:1 in each theme. Without
colour-dark, the dark theme usescolour. - To hide a section changes only the menus and the home page. It does not change access: a link to a hidden namespace or control domain still opens for a user who can read it.
- The extensions heading is "Extensions". If you hide namespaces and control domains, the menu and home page show no heading unless you set one.
- The start page is
/,/search,/namespace/<namespace>,/domain/<domain>,/extensions/<extension-id>/<screen-id>or/chat. The UI opens it only when a user opens the root URL. If the extension screen or chat is not available, or the UI cannot get its settings or the extension list within 3 seconds, the UI shows the home page. - The UI gets the logos from
GET /api/calm/ui/branding/logo/{light|dark}, which requires authentication.
To white-label CALM Hub, set a name, a logo and a brand colour. They replace the CALM name, logo and colours in the header, the home page, the browser tab title and the search boxes. If you set no name, the tab title stays "CALM", the search boxes name CALM Hub, and the CALM logo shows when the browser cannot show your logo. No setting changes these parts, which still show CALM:
- The browser tab icon is always the CALM icon.
- The browser tab title is "CALM" until the UI gets its settings, which requires authentication.
- The UI shows the CALM name and logo if it cannot get its settings.
- Some UI messages name CALM Hub, for example on the chat page, in extension forms and screens, and on the Decorators tab. The CALM diagram lens keeps its name.
CALM_UI_ENVIRONMENT_NAME=UAT
CALM_UI_ENVIRONMENT_COLOUR=warning # info | success | warning | error | neutral | #rrggbb
CALM_UI_IDENTITY_ENABLED=true # shows the principal name that CALM Hub sees
CALM_UI_ITEMS_0__LABEL=Support
CALM_UI_ITEMS_0__URL=https://support.example.com
CALM_UI_ITEMS_1__LABEL=Build
CALM_UI_ITEMS_1__VALUE=2026.10.1
- Each item needs a
labeland avalue, aurl, or both. With both, thevalueis the link text. - Use a short environment name, for example
DEV,QAorPROD. The header cuts a long name to fit, and cuts it most on a narrow screen. Tap or click the pill to see the full name. - CALM Hub does not start if a name, colour, logo, layout, start page or URL is not valid. URLs must be absolute
httporhttpsURLs. - Identity and roles are off by default. Turn on
show-rolesonly if your role names are safe to show to users. - The UI gets these values from
GET /api/calm/ui/config, which requires authentication.
Extensions
An extension adds features to CALM Hub without a fork. It is an HTTP service that CALM Hub calls. The operator installs it with a manifest. CALM Hub reads the manifests at start up. No API adds an extension.
The Hub UI shows the contributions of an extension, the CLI runs its commands (see Running extension commands), and MCP makes a tool for each command (see Extension tools).
| Page | Read it to |
|---|---|
| Extensions | Find an extension and install it |
| Build and install an extension | Follow a tutorial from the manifest to the UI, CLI and MCP |
| Extension points | Find the fields, the context and the limits of each extension point and of commands |
| Extension blocks | Write the JSON that the UI draws |
| Extension navigation | Link to an architecture, a node or an extension screen, and return to the same place |
| Decorator views | Draw decorators on the diagram, with no backend |
| The C4 extension | See a diagram lens with its own notation, run as a sidecar |
| The ea-layers extension | See a smaller diagram lens, in the ArchiMate® notation |
| Extension access | Learn the scopes, the identity assertion and the trust model |
Put one folder for each extension in calm.extensions.dir, with an extension.json in it. The folder name must equal the manifest id. Hub skips hidden folders and warns about folders without a manifest. A per-id setting for an unknown extension id gives a warning at start up, as a property or as an environment variable.
/etc/calm-hub/extensions/
└── team-services/
└── extension.json
| Setting | Default | Purpose |
|---|---|---|
calm.extensions.dir | not set | The folder of manifests. When it is not set, CALM Hub loads only the built-in decorator views |
calm.extensions."<id>".enabled | true | Set false to turn off an extension |
calm.extensions."<id>".order | 0 | Lower values come first in the list. Equal values sort by id |
calm.extensions."<id>".backend-url | not set | The base URL of the extension service. Required for an enabled extension with routes |
calm.extensions."<id>".allow-http | false | Allows a plain http backend that is not on loopback, such as a cluster-internal host. Otherwise the backend must use https, or http on localhost, 127.x.x.x or [::1] |
calm.extensions."<id>".send-identity | true | false sends no identity assertion to the extension, for an open service that answers any caller. CALM Hub then needs no identity keys for it. Allowed only when every route of the extension is a GET or readOnly route. CALM Hub still checks the route scope for the user |
calm.extensions."<id>".connect-timeout-seconds | calm.extensions.http.connect-timeout-seconds (5) | The connect timeout for each call. A value below 1 stops start-up |
calm.extensions."<id>".request-timeout-seconds | calm.extensions.http.request-timeout-seconds (10) | The limit for the whole call. A slow backend gets 504. A value below 1 stops start-up |
calm.extensions."<id>".max-request-bytes | calm.extensions.http.max-request-bytes (1048576) | A larger request body gets 413. A value below 1 stops start-up |
calm.extensions."<id>".max-response-bytes | calm.extensions.http.max-response-bytes (1048576) | A larger reply gets 502. A larger streamed reply ends with an error event. A value below 1 stops start-up |
calm.extensions."<id>".max-concurrent-calls | calm.extensions.http.max-concurrent-calls (32) | The calls to the extension at the same time. One more call gets 503 with Retry-After: 1, so that a slow backend cannot hold every worker thread. A value below 1 stops start-up |
calm.extensions."<id>".max-concurrent-streams | calm.extensions.http.max-concurrent-streams (8) | The streamed replies of the proxy and MCP from the extension at the same time. Chat replies have their own pool. Each stream holds a worker thread until it ends. One more stream gets 503 with Retry-After: 1. A value below 1 stops start-up |
calm.extensions."<id>".max-concurrent-chat-streams | calm.extensions.http.max-concurrent-chat-streams (8) | The chat replies from the extension at the same time, so that proxy streams cannot use up the chat. One more chat reply gets 503 with Retry-After: 1. A value below 1 stops start-up |
calm.extensions."<id>".max-concurrent-streams-per-user | calm.extensions.http.max-concurrent-streams-per-user (2) | The streamed replies of one user from the extension at the same time, in each of the two pools, so that one user cannot hold every slot. With auth off, every caller is the one no-auth user, so all callers share this limit. One more stream gets 503 with Retry-After: 1. A value below 1, or above max-concurrent-streams or max-concurrent-chat-streams, stops start-up |
calm.extensions."<id>".stream-idle-timeout-seconds | calm.extensions.http.stream-idle-timeout-seconds (30) | The longest wait for the next part of a streamed reply. A value below 1 stops start-up |
calm.extensions."<id>".max-stream-seconds | calm.extensions.http.max-stream-seconds (300) | The longest time, from when the backend reply arrives, that CALM Hub keeps the backend connection and the stream slot of a streamed reply. Then CALM Hub closes both, also for a reply that it never sent on. A stream that CALM Hub is sending ends with an error event. A value below 1 stops start-up |
calm.extensions.chat-provider | not set | The chat that the Hub UI shows: <extension-id>, or <extension-id>/<chat-entry-id> for an extension with more than one chat entry. With no setting, there is no chat |
calm.extensions.identity.private-key-location | not set | The PKCS#8 PEM key that signs the identity assertion: RSA (2048 bits or more, RS256) or P-256 (ES256). Required when an enabled extension that sends identity assertions has routes. A shared secret (HS256) is refused |
calm.extensions.identity.public-key-locations | not set | Comma-separated PEM public keys for the JWKS. The first is the public key of the signing key. Required when private-key-location is set, and not allowed without it |
calm.extensions.identity.ttl-seconds | 60 | The lifetime of an assertion, at most 300 |
calm.extensions.allow-without-auth | false | Allows enabled extensions with routes when calm.auth.enabled=false. Only for local development: every caller is then a global admin |
CALM_EXTENSIONS_DIR=/etc/calm-hub/extensions
CALM_EXTENSIONS__TEAM_SERVICES__BACKEND_URL=https://team-services.internal
CALM_EXTENSIONS__TEAM_SERVICES__ORDER=10
The manifest declares:
id,version,hubApi(now0),name, and optionaldescription,providerandlogo(see Extension logos).routes: every call that the extension can receive, each with anid,method,path,scope, and optionalreadOnlyandhubData(the data that CALM Hub reads for the user and sends as the body, see Let CALM Hub send the data). Aread,writeoradminscope needs a{namespace}in the path. Adomain_*scope needs a{domain}. A path parameter cannot contain a slash, so a route for a CALM Hub resource uses{resourceType}/{resourceId}, not{resource}. When two routes with the same method match a path, the route with more literal segments wins. CALM Hub does not start if two such routes have the same number, for exampleGET /{namespace}/reportandGET /public/{id}.commands: CLI and MCP commands, keyed by name. Each names a route byid.contributes: the UI extension pointsscreen,designer-tab,landing-card,detail-panel,action,form,search-providerandchat, which name a route byid,decorator-views, which CALM Hub draws from decorators with no route, anddiagram-lens, a picture of an architecture that CALM Hub draws from a graph reply and a notation. A decorator viewidand a lensidmust each be unique in all enabled extensions.
The JSON Schema is META-INF/calm-extensions/schema/0/extension.schema.json in the CALM Hub jar. Unknown fields are errors. See the example manifest.
- CALM Hub does not start if a manifest or a setting is not valid. The error names the file or the setting.
GET /api/calm/extensionslists the enabled extensions, for any signed-in user. It never shows the backend URL. On a read-only CALM Hub it leaves out write routes that are notreadOnly, and the commands and contributions that use them.
Extension logos
An extension can show a logo beside its name: in the side menu, on its home page card, above the heading of its screens, in the inspector beside the diagram, and in search and chat. The name always shows as text. Without a logo, while the logo loads, or when the logo does not load, CALM Hub shows the generated marker of the extension.
"logo": { "light": "logo.svg", "dark": "logo-dark.svg" }
| Field | Required | Rule |
|---|---|---|
light | Yes | The logo for the light theme. In the dark theme, CALM Hub shows it on a light plate when there is no dark file |
dark | No | The logo for the dark theme |
Each value is a file name in the extension folder, next to extension.json: lowercase letters, digits, ., _ and -, with no path. CALM Hub reads each file at start up and does not start if a file:
- is not a PNG, JPEG, WebP or SVG file, or does not hold the type of its extension (
.png,.jpg,.jpeg,.webp,.svg) - is larger than 256 KiB, or is a PNG, JPEG or WebP image with a side larger than 2048 pixels
- is an SVG file with a DOCTYPE, an entity, a processing instruction, a
script,foreignObjector HTML element, anon*attribute, a link or CSSurl()that is not a#fragment, anxml:baseattribute, an animated link orxml:base, a CSS@import,image-set(),src()or escape
Use a square image that reads at 16 pixels. CALM Hub never fetches a logo from a URL.
The UI reads a logo from GET /api/calm/extensions/<id>/logo/<light|dark>, which needs a signed-in user. The reply has the exact image type, X-Content-Type-Options: nosniff, Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; sandbox, an ETag and Cache-Control: private, no-cache. The UI shows the image only in an img element, from a data: URL. A browser runs no script and loads no other resource in an SVG image. A data: URL has an opaque origin, so an SVG file that is opened as a page cannot read CALM Hub data. If you set a Content-Security-Policy for CALM Hub UI, allow img-src data:. Without it, the UI shows the markers.
Calling an extension
CALM Hub proxies each declared route at /api/calm/extensions/<id>/api/<route path>. A route with the path / is at /api/calm/extensions/<id>/api/, with the trailing slash. Without it, CALM Hub gives 404, also on a CALM Hub that is not read-only. For each call, CALM Hub:
- refuses an encoded slash (
%2F, in any case, or double-encoded) with400, and does not call the backend. A backend that decodes%2Fbefore routing would see a path other than the one CALM Hub checked. For the same reason, it refuses an encoded look-alike of/or\(U+2044, U+2215, U+2216, U+29F5 and U+29F8), each code point whose NFKC form contains/or\(U+2100, U+2101, U+2105, U+2106, U+FE68, U+FF0F and U+FF3C), and each code point whose NFKC form is only.,%,@or;(U+037E, U+2024 to U+2026, U+FE14, U+FE19, U+FE30, U+FE52, U+FE54, U+FE6A, U+FE6B, U+FF05, U+FF0E, U+FF1B and U+FF20). For example, NFKC makes U+2025..and U+2100a/c - refuses a matrix parameter (
;name=value) with400, and does not drop it - decodes percent-encoded unreserved characters and uppercases other escapes before matching and forwarding. Percent-encoding in a matched literal segment gets
400 - on a read-only CALM Hub, gives
405, not400, to aPOST,PUT,PATCHorDELETEwith%2F,%2E,%5C,%25,%40,..,\,//,@,;or an encoded look-alike of/,\,.,%,@or;in the path. CALM Hub refuses such a path before it finds the route - gives
415, before it signs the assertion, to aPOSTthat has noapplication/jsonor other+jsonContent-Type, also when it has no body. APUT,PATCHorDELETEgets415only for a body of another type. Thus a cross-site form or fetch cannot call a route as the user. Those three methods need a CORS preflight, which CALM Hub does not allow cross-site - matches the path against the declared routes only, and refuses
..,%2e,\,//,@and their encoded forms - checks the route
scopewith the same rules as the rest of CALM Hub. The namespace or domain comes only from the path - on a read-only CALM Hub, allows a method other than
GETonly on areadOnlyroute. Its405, and the405for a method that the route does not declare, has anAllowheader. It lists only the methods that CALM Hub accepts on that path now, andHEADwithGET, because CALM Hub answersHEADwith theGETroute - sends only
Content-Type,Accept,Accept-Language,If-Match,If-None-Matchand its ownX-Calm-Hub-Identityassertion. A header value with a line break gets400. The caller's token and cookies never go to the extension - returns only
Content-Type(application/json,text/plainortext/event-stream, and for a4xxreply alsoapplication/problem+jsonand other+jsontypes),Cache-Control,ETag,Retry-AfterandVary, and addsContent-Security-Policy: sandbox; default-src 'none'. It returns them only on a reply that it passes on: a backend503becomes502withoutRetry-After. It passes on a304. It does not follow redirects, and does not returnLocation, because that would name the private backend - marks each reply
Cache-Control: private, because the reply is for one user. It removespublic, and keeps the other directives of the backend. Its own error replies are alsoprivate - returns
502or504, with a generic body, when the backend fails, is slow, replies with5xx,401,407or a3xxother than304, or sends another content type - audits every non-
readOnlycall, includingGET, and every chat message of a signed-in user, as entity typeEXTENSIONwith the extension id, route id and assertionjti. The entry has the namespace only for aread,writeoradminroute, or for a chat message that shares a resource (then also its type, id and version), and the domain only for adomain_*route. Outcomes areSUCCESS,DENIED,FAILURE(a refusal after the scope check, such as400,413,415or503, or a returned client error), orUNKNOWN(an upstream failure or unusable reply; the backend may have completed the call). The entry has thejtionly when CALM Hub sent the call, and the source IP (theX-Forwarded-Forheader of the REST or MCP request) whencalm.audit.capture-source-ip=true
A 200 text/event-stream reply streams to a caller whose Accept names text/event-stream: CALM Hub sends each event on when it arrives, with only its event and data lines. Other replies are buffered. The stream limits are max-concurrent-streams (max-concurrent-chat-streams for the chat), max-concurrent-streams-per-user, stream-idle-timeout-seconds, max-stream-seconds (from when the reply arrives) and max-response-bytes. At a limit, CALM Hub ends the stream with an error event. When the caller closes the stream, CALM Hub closes the connection to the backend. If the caller left before the backend replied, CALM Hub closes it when the reply arrives. CALM Hub has no time limit for a write to the caller: a caller that stops reading holds a worker thread of CALM Hub until its connection fails, also after the stream limits have freed the slot and closed the backend connection. A HEAD request gets the headers of the stream, and CALM Hub then closes the stream at once.
The route of a chat entry answers only at /api/calm/extensions/<id>/chat/<entry>. The proxy and MCP refuse it with 404.
A form route is not at this path: it gives 404 there. Hub calls it only from
POST /api/calm/extensions/<id>/forms/<form>, after it checks the target and the input. That endpoint
uses the same scope, read-only, limit and audit rules (see form).
CALM Hub does not audit an extension call that it refuses before the scope check: a 401 for a caller who is not signed in, a 404, a 400 for the path, the namespace or the domain, or a 405.
CALM Hub does not start with an enabled extension that has routes when calm.auth.enabled=false, because every caller is then a global admin. Set calm.extensions.allow-without-auth=true only for local development.
Identity keys
CALM Hub signs a short-lived JWT for each call to an extension, unless the extension has send-identity=false. It publishes the public keys at GET /api/calm/auth/jwks. This endpoint is public. Set calm.hub.base-url to the URL that the backends expect in iss. When it is not set, iss is http://localhost:8080, and CALM Hub gives a warning at start up if an enabled extension that sends identity assertions has routes. Create a key pair:
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out hub-private.pem
openssl pkey -in hub-private.pem -pubout -out hub-public.pem
To change the key with no outage, put the new key first and keep the old public key in the list for at least ttl-seconds:
CALM_EXTENSIONS_IDENTITY_PRIVATE_KEY_LOCATION=/keys/new-private.pem
CALM_EXTENSIONS_IDENTITY_PUBLIC_KEY_LOCATIONS=/keys/new-public.pem,/keys/old-public.pem
In proxy-auth mode, any client that reaches CALM Hub directly can set Remote-User. Make CALM Hub listen only on loopback or behind the proxy.
For extension authors
Verify X-Calm-Hub-Identity on each request, and return only what the user may see. See Extension access for the claims, the checks and the trust model, and the example backend.
Docker Hub Images
All images are published to Docker Hub at finos/calm-hub.
The latest tags point to the most recent release. Each release also has its own tags, for example
0.8.0 and 0.8.0-native, which never change. The changes in each release are in the
CALM Hub changelog.
docker pull finos/calm-hub:latest
docker pull finos/calm-hub:latest-native
docker pull finos/calm-hub:latest-read-only-static
docker pull finos/calm-hub:latest-read-only-native
GitHub Actions Build Status
CI Builds
| Workflow | Status |
|---|---|
| Integration tests & coverage | |
| Unit test coverage |
Docker Image Publishing
| Workflow | Image tag | Status |
|---|---|---|
| JVM image (MongoDB) | latest | |
| Native image (MongoDB) | latest-native | |
| Read-only JVM image | latest-read-only-static | |
| Read-only native image | latest-read-only-native |
All docker-publish workflows include an automated smoke test that validates the image before pushing. See smoke-test.sh for the assertion script.
Quick Start
Read-Only (no dependencies)
docker run --rm -p 8080:8080 finos/calm-hub:latest-read-only-static
# API: http://localhost:8080/calm/namespaces
# Swagger: http://localhost:8080/q/swagger-ui
With MongoDB
# Start MongoDB
cd calm-hub/local-dev && docker-compose up -d
# Start CALM Hub (JVM)
cd calm-hub && ../mvnw quarkus:dev
Show your decorators in Hub
An external service can write decorators with its own service account and ship a views-only manifest. Hub draws the results; the service supplies no browser code.
- Give the service account write access to the target namespace. Use that account's credentials with the decorator API, not a user's token. If the decorator type is reserved, the operator must also allow this principal to write that type.
- Write decorators with a stable
type, architecture version URLs intarget, element ids inapplies-to, and results indata. A known$schemais validated on write. For a reserved type,PUTthe new result to the current decorator id (the id that the last write returned). Hub stores it as a new decorator and keeps the old one in the history. - Put this manifest at
<calm.extensions.dir>/scanner/extension.json, then restart Hub:
{
"id": "scanner",
"version": "1.0.0",
"hubApi": 0,
"name": "Security scan",
"contributes": {
"decorator-views": [{
"id": "security-scan",
"match": { "type": "security-scan" },
"label": "Security scan",
"overlay": {
"status": "/result",
"map": { "safe": "ok", "unsafe": "error" },
"default": "info"
}
}]
}
}
No routes or backend URL are needed. See Decorator views for the fields, how Hub draws a view, the legend, and the built-in control-evaluation and deployment views.
Further Reading
- UI Walkthrough - visual interface guide (namespace explorer, diagram canvas, timeline, compare mode)
- Developer Guide - test pyramid, storage extension points, running CALM Hub from any data source
- MCP & API Reference - Model Context Protocol tools, OpenAPI spec, Swagger UI
- Build and install an extension - tutorial with the release-tracker demo extension
- Extension points, Extension blocks, Extension navigation, Decorator views, Extension access - extension reference