Moorhold docs

These are the endpoints on a Moorhold server that something other than a person's browser may call: a launcher page, a monitor, or an agent. This page describes the latest release (2026.11.4).

Everything public is at https://<hostname>, behind the server's front (Caddy). The tools in the Stack's spec.public.publish are at their own names under it, such as https://superset.<hostname>.

Terminal window
curl -s https://<hostname>/api/moorhold/health

GET /api/moorhold/health says whether this is a Moorhold server and whether it's ready. It needs no sign-in and sets no cookie.

Status Body Means
200 {"moorhold":true,"status":"ok"} The portal holds its Stack, and the sign-in service has answered.
503 {"moorhold":true,"status":"starting"} Anything short of that: first run, or the database or Keycloak isn't up.
403 empty The request came from a page whose origin isn't allowed.

It holds no version, hostname, component or error text. The server checks at most once every five seconds, whoever asks, and the answer is sent with Cache-Control: no-store, max-age=0.

A request with no Origin header, such as curl or a monitor, gets the answer. A page may read it across origins only from one of the Stack's spec.public.launcherOrigins (default https://moorhold.dev), with GET and no credentials. OPTIONS answers a preflight from an allowed origin with 204, and any other origin with 403.

GET /launch is where a launcher hands a person to this server. It takes no parameters. It answers 302: to the portal's home when the person is signed in, otherwise to this server's own Keycloak sign-in, which comes back to the portal's home.

The portal's sign-in uses routes under /auth: login, callback, logout, signed-out, refresh, session, first-run-state, local, error, session-guard and backchannel-logout. They're for the portal's own pages and Keycloak, and nothing else should call them. The front answers 404 to /auth/session-guard and /auth/backchannel-logout from outside the server.

Unless the Stack's spec.public.index is true, the front sends X-Robots-Tag: noindex, nofollow on every response from the portal and from each published tool, and answers GET /robots.txt itself with User-agent: * and Disallow: /. With index: true it sends no such header, and robots.txt allows every path. In 2026.11.3 robots.txt comes out as one line: see Known issues.

The portal's MCP server, for agents. On an installed server it listens on 127.0.0.1:8096, on the server only.

Method and path Needs What it is
GET /health nothing {"ok":true} while it runs.
GET /.well-known/oauth-protected-resource nothing Its OAuth protected resource metadata: the resource, the authorization_servers (the stack's Keycloak), bearer_methods_supported (header) and resource_name (moorhold-portal).
GET /.well-known/moorhold/mcp-endpoints nothing Each tool's own MCP server, as list_mcp_endpoints returns it.
POST /mcp a bearer token MCP requests. See the portal MCP tools reference.

POST /mcp without a valid token answers 401 with a WWW-Authenticate header that points to the resource metadata. Another method on /mcp answers 405. A request whose Origin isn't allowed answers 403. A body over 1,000,000 bytes answers 413.

The front answers 404 to these from outside the server:

Site Paths
https://<hostname> /admin, /realms/* except the server's own realm, /health, /metrics, /auth/session-guard, /auth/backchannel-logout
https://superset.<hostname> /api/v1/security/login*, /api/v1/security/refresh*, /api/v1/security/guest_token*, /metrics
https://datahub.<hostname> /logIn*, /signUp*, /resetNativeUserCredentials*, /admin, /metrics
https://airflow.<hostname> /auth/token*, /auth/fab/v1/*, /execution/*, /metrics

People sign in to every tool through Keycloak. The tools' own sign-in APIs, used by Moorhold's reconciler, stay on the server's internal network.

Each client address may make 600 requests a minute to each site. An IPv6 client counts as its whole /64. On https://<hostname>, these paths have a limit of 30 requests a minute from one client:

  • /auth/local* and /sign-in/local*, the local admin's sign-in
  • /setup*, the setup code step
  • /realms/<realm>/login-actions/*, Keycloak's sign-in forms

Keycloak's token endpoint isn't limited.

The front keeps an access log of every request, for 30 days. It holds no query strings and no headers, and each client address is cut to its /24 (IPv4) or /48 (IPv6). The tools are sent the same cut address.