Configuration

Coral stores local configuration in config.toml inside its platform-specific local state directory.

Managed state

Coral writes source installation state to config.toml when you run commands such as coral source add and coral source remove. This state includes installed-source metadata and non-secret source variables. Source secrets are stored separately within the same local trust boundary.

Prefer the coral source commands for source state instead of editing workspace entries manually.

Database

Coral stores durable app state in a local SQLite database named coral.db inside the local state directory by default. You do not need a [database] section for the default setup. Use [database] to choose an explicit backend. Relative SQLite paths resolve from the local state directory.

[database]
backend = "sqlite"
path = "state/coral.db"

For Postgres, store the connection URL in an environment variable and reference the variable name from config.toml.

[database]
backend = "postgres"
url_env = "CORAL_DATABASE_URL"

export CORAL_DATABASE_URL="postgres://coral:secret@db.example.com:5432/coral?sslmode=verify-full"

Remote Postgres URLs must set sslmode=verify-full so Coral verifies the server identity. Loopback and local-socket Postgres URLs may omit TLS for local development.

Workspaces

Which workspaces exist is recorded in Coral’s database, not in config.toml. There is no automatically created workspace: a fresh install has none until you run coral workspace create NAME, and Coral never falls back to a name of its own. default is an ordinary name you may create, remove, and select like any other. What config.toml holds is the per-workspace installation state for the things you install into a workspace — sources and functions:

[workspaces.work.sources.github]
version = "1.0.0"
variables = {}
secrets = ["GITHUB_TOKEN"]
origin = "bundled"

Coral writes these tables when you run commands such as coral source add. Creating an empty workspace writes no [workspaces.<name>] scaffolding, so a workspace with nothing installed in it appears in coral workspace list without appearing in config.toml. There is no active-workspace key in config.toml; use CORAL_WORKSPACE for a shell default or --workspace <NAME> for one command, as described in Global workspace selection. Source specs imported from files and source credential material remain scoped to the source installation in a workspace. Reusable global source specs and reusable credential references are not config objects today.

Server

The long-running coral server command reads its native gRPC bind address from [server]:

[server]
bind_addr = "127.0.0.1:14555"

bind_addr must be a literal IP address and port, not a hostname. Without a [server] section, Coral binds an ephemeral port on 127.0.0.1.

Without [auth] configured, the native gRPC server does not authenticate clients: a non-loopback bind exposes Coral and its configured sources to any client that can reach the port. With [auth] configured, gRPC requests require a bearer access token — only the gRPC health service stays unauthenticated, so orchestrator probes keep working — but the listener still serves cleartext h2c, so those tokens can be read off the wire. Either way, protect a non-loopback bind with a trusted network boundary and terminate TLS in front of Coral.

Coral terminates no TLS on any listener. For any deployment that leaves loopback, run a TLS-terminating reverse proxy in front of Coral. See Self-host Coral with Docker and Deploy Coral on Kubernetes. MCP Streamable HTTP is disabled by default. Enable its companion listener under [server.mcp_http]:

[server.mcp_http]
enabled = true
bind = "127.0.0.1:14556"

Key	Type	Default	Description
`enabled`	boolean	`false`	Starts the MCP Streamable HTTP listener alongside the gRPC server.
`bind`	string	`127.0.0.1:0`	Listener address as a literal IP and port. Loopback-only without `[auth]` unless opted in below.
`public_url`	string	unset	Externally reachable base of the per-workspace MCP URLs. Required when the listener is enabled with `[auth]`; forbidden without `[auth]`.
`allow_unauthenticated_non_loopback`	boolean	`false`	Opt-in that lets the unauthenticated listener bind non-loopback addresses. Rejected with `[auth]`.
`allowed_hosts`	array of strings	`[]`	Extra `Host` header names the unauthenticated listener accepts. Rejected with `[auth]`.

Every workspace is served at its own MCP URL on this listener, /mcp/workspace/{workspace} — for example /mcp/workspace/analytics — next to GET /livez and GET /readyz health routes. There is no single-workspace endpoint and no workspace key: the URL a client connects to names the workspace its sessions reach, a workspace is reachable as soon as it exists, and the retired /mcp path answers not-found. Without [auth], the listener is unauthenticated, public_url must stay unset, and the listener is restricted to loopback addresses by default. To serve it on other interfaces — necessary inside a Docker container, where a loopback bind is unreachable through published ports — opt in explicitly:

[server.mcp_http]
enabled = true
bind = "0.0.0.0:14556"
allow_unauthenticated_non_loopback = true

The opted-in listener performs no authentication: anything that can reach the port can read every configured source with the local user’s full authority. Keep it reachable only from trusted machines. In Docker, publish the port to loopback only (-p 127.0.0.1:14556:14556 — a bare -p 14556:14556 exposes it on every host interface), or keep it unpublished on an internal network. For anything beyond a single trusted machine, configure Coral’s authenticated serving mode (the [auth] section) instead.

The listener accepts requests whose Host header names localhost, 127.0.0.1, ::1, or the bind IP; other values are rejected to block DNS-rebinding attacks. When clients reach the listener under another name — for example a Docker Compose service name or the machine’s LAN address — list the extra names explicitly:

[server.mcp_http]
allowed_hosts = ["coral"]

With [auth], bind may be any address and an enabled listener must set public_url; it is the public base the per-workspace URLs hang under, for example https://mcp.example.com/mcp serving each workspace at https://mcp.example.com/mcp/workspace/{workspace}. Each such workspace URL — never the base itself — is its own OAuth resource identifier and token audience, with its own protected-resource metadata document, so a token minted for one workspace’s URL is invalid at every other’s. The listener mounts the family under the base’s path, so keep that path consistent with what the ingress forwards. Both opt-in keys are rejected when [auth] is configured: remote binds then need no opt-in, and accepted hosts derive from public_url, the bind IP, plus the loopback names.

Authentication

Authentication is off by default: without an [auth] section, coral server runs in single-user local mode and does not authenticate callers. Adding [auth] turns the server into an OAuth 2.1 authorization server that delegates login to one upstream OIDC identity provider and mints its own bearer access tokens for Coral UI and MCP clients.

[auth]
http_bind_addr = "0.0.0.0:8081"
allowed_audiences = ["https://coral.example.com"]

[auth.session]
signing_key_env = "CORAL_SESSION_SIGNING_KEY"

[auth.authorization_server]
issuer = "https://auth.coral.example.com"

[auth.provider]
issuer = "https://your-idp.example.com"
client_id = "coral"
client_secret_env = "CORAL_OIDC_CLIENT_SECRET"
redirect_uri = "https://auth.coral.example.com/auth/oidc/callback"

Configuring [auth] requires at least one public surface: an enabled [server.mcp_http] with public_url, a non-empty allowed_audiences, or both. Startup fails otherwise.

Coral’s authorization server, gRPC listener, and MCP listener all serve cleartext. Bearer tokens cross the wire unprotected unless a TLS-terminating reverse proxy fronts every non-loopback listener. The configured issuer, public_url, and audience URLs must match the external TLS hostnames exactly.

`[auth]`

Key	Type	Default	Description
`http_bind_addr`	string	`127.0.0.1:0`	Bind address for the authorization server’s HTTP listener. May bind non-loopback for proxied deployments.
`allowed_audiences`	array of strings	`[]`	Resource identifiers tokens may be minted for in addition to `[server.mcp_http].public_url`, such as a deployed Coral UI origin.

`[auth.session]`

The [auth.session] table must be present whenever [auth] is configured — a bare [auth.session] header is enough to accept every default.

Key	Type	Default	Description
`signing_key_env`	string	`CORAL_SESSION_SIGNING_KEY`	Environment variable holding the token signing key as base64-encoded PKCS#8 P-256 DER.
`signing_key_file`	string	unset	Path to the signing key as raw PKCS#8 P-256 DER bytes, resolved from the directory containing `config.toml`. Mutually exclusive with `signing_key_env`.
`access_token_ttl_seconds`	integer	`2592000` (30 days)	Lifetime of minted access tokens. Maximum one year. Clients log in again after expiry.

Generate a signing key with:

openssl ecparam -genkey -name prime256v1 -noout \
  | openssl pkcs8 -topk8 -nocrypt -outform DER \
  | base64 | tr -d '\n'

Export the output as CORAL_SESSION_SIGNING_KEY (or store the DER bytes in a file referenced by signing_key_file). PEM keys are not accepted.

`[auth.authorization_server]`

Key	Type	Default	Description
`issuer`	string	required	Coral’s own OAuth issuer URL. HTTPS (or explicit-loopback HTTP), mounted at the origin root, no path.
`trusted_clients`	array of strings	`[]`	Client-ID URLs whose sign-ins skip Coral’s approval page. Entries are validated at startup and matched exactly against the request’s client ID.

Every sign-in normally pauses on Coral’s approval page before redirecting to the identity provider. List a first-party client you operate yourself — for example a deployed Coral UI’s <public URL>/.well-known/oauth-client — in trusted_clients to send its sign-ins straight to the provider. Trust removes only the approval step; client metadata resolution, redirect-URI registration, PKCE, and resource validation are unchanged. Avoid listing clients with loopback redirect URIs: any local process can claim a loopback port, and the approval page is the only step that shows which port receives the authorization code. The authorization server serves GET /.well-known/oauth-authorization-server, GET/POST /oauth/authorize, POST /oauth/token, and GET /auth/oidc/callback on the http_bind_addr listener. The reverse proxy must forward the issuer origin to it at the root.

`[auth.provider]`

The single upstream OIDC provider Coral delegates login to. Who can sign in is decided entirely by this provider and required_claims; Coral keeps its own record of every user who has signed in, and its own per-workspace memberships, but delegates the sign-in decision itself.

Key	Type	Default	Description
`issuer`	string	required	Upstream OIDC issuer URL, matched byte-for-byte against its discovery document.
`client_id`	string	required	Client ID registered with the upstream provider.
`client_secret`	string	—	Client secret value. Exactly one of `client_secret` or `client_secret_env` must be set.
`client_secret_env`	string	—	Environment variable holding the client secret.
`redirect_uri`	string	required	Must be exactly `{authorization_server.issuer}/auth/oidc/callback`.
`scopes`	array	`["openid", "email", "profile"]`	Scopes requested from the provider. Must include `openid`.
`principal_claim`	string	`sub`	ID-token claim used to derive the stable Coral principal ID.
`display_name_claim`	string	`email`	ID-token claim shown as the signed-in user’s display name.
`required_claims`	table	`{}`	Claim values the ID token must carry, e.g. `required_claims = { hd = "example.com" }`.
`auth_params`	table	`{}`	Extra authorize-request parameters. Reserved OAuth parameters are rejected.
`discovery_cache_ttl_seconds`	integer	`300`	How long provider discovery metadata is cached. Maximum one hour.

Signing in grants no workspace access by itself. Access is granted per workspace, at Owner or Member level, through workspace memberships — see Shared server access control for what each role may do. The provider and required_claims decide who can sign in at all; membership decides what a signed-in user reaches.

MCP HTTP workspace URLs

Nothing under [server.mcp_http] selects a workspace: every workspace is served at its own URL, /mcp/workspace/{workspace} under the listener (and under public_url when [auth] is configured). A workspace key is rejected at startup — earlier releases used it to bind the listener to one workspace, and a value that silently stopped meaning that would be worse than an error. Whether a URL serves is a per-handshake question, never a startup one. The server starts with zero workspaces, a workspace created while it runs is immediately reachable at its URL, and a deleted one immediately answers not-found to new sessions. Only URL-safe workspace names (ASCII letters and digits plus -, ., _, ~) are reachable over HTTP; a workspace named outside that set stays fully usable over gRPC and stdio but has no URL until it is recreated under a URL-safe name. Without [auth], requests act as the built-in local user with full access to every workspace URL. With [auth], a session is admitted only when the URL’s workspace is among the calling token’s own memberships — see Shared server access control for the admission and concealment contract.

Runtime features

Experimental runtime features are configured under [features].

[features]
feedback = true

You can inspect available features and their effective state with:

coral features list

Enable or disable a feature with:

coral features enable feedback
coral features disable feedback

Feature values must be booleans. Unknown feature keys are preserved in config.toml but ignored by Coral.

Feature	Default	Description
`database_sources`	`false`	Experimental. Enables installing and querying database sources.
`feedback`	`false`	Experimental. Exposes the MCP feedback tool when enabled. Feedback reports are stored locally and anonymous copies may be uploaded to Coral.
`observed_values_search`	`false`	Experimental. Collects, indexes, retrieves, and maintains values observed during earlier queries.

OpenTelemetry

External OpenTelemetry export is configured under [otel].

[otel]
endpoint = "http://localhost:4318"
headers = "authorization=Bearer ..."
log_filter = "info"
trace_filter = "coral_app=debug"
service_name = "coral"

Trace history settings are configured under [trace_history].

[trace_history]
enabled = true
retention_days = 7

See Observe with OpenTelemetry for the full telemetry setup guide.

Get started

Guides

Reference

Project

Managed state

Database

Workspaces

Server

Authentication

`[auth]`

`[auth.session]`

`[auth.authorization_server]`

`[auth.provider]`

MCP HTTP workspace URLs

Runtime features

OpenTelemetry

​Managed state

​Database

​Workspaces

​Server

​Authentication

​[auth]

​[auth.session]

​[auth.authorization_server]

​[auth.provider]

​MCP HTTP workspace URLs

​Runtime features

​OpenTelemetry

Managed state

Database

Workspaces

Server

Authentication

`[auth]`

`[auth.session]`

`[auth.authorization_server]`

`[auth.provider]`

MCP HTTP workspace URLs

Runtime features

OpenTelemetry