Skip to main content
Your configuration lives in the config.toml file of Coral’s configuration folder. By default the folder is located in:
  • macOS: ~/Library/Application Support/com.withcoral.coral
  • Linux: ~/.config/coral
  • Windows: %APPDATA%\withcoral\coral\config
You can override the location of the config folder with the CORAL_CONFIG_DIR environment variable.

General

[listeners.grpc]

[listeners.mcp]

[listeners.auth]

[listeners.web]

[credentials]

[outbound]

Controls the policy for outbound calls from Coral to providers. Policies can have one of the following values:
  • deny: Denies all requests to the policy target
  • https: Allows only https requests, no plain http.
  • http-and-https: Allows both http and https requests.
All provider calls not covered by an explicit policy in this section are treated under the https policy.

[runtime]

[updates]

When the check is on, Coral reads the latest release from api.github.com at startup and every 6 hours. Organization owners then see a newer release in the sidebar. The [outbound] policy still applies. Coral Desktop turns the check on when it can update itself. There, a click on the notice offers Restart to Update, Release Notes or Later.

[otel]

Controls telemetry export to an OpenTelemetry endpoint. Every request has a trace, even when you do not set endpoint. A failed MCP tool call returns its trace_id. trace_filter controls which spans Coral exports, not which requests are traced. Request spans use the target coral.request. trace_sample_ratio controls which traces Coral exports. It applies to each trace Coral starts: a request without a valid caller traceparent, and each Program Run, which starts its own trace. A request with a valid caller traceparent follows the caller’s sampled flag. An unsampled trace keeps its trace ID, so logs and tool failures still name it. Metrics are never sampled.

Trace UI requests

The UI reads the standard OpenTelemetry environment variables at startup, not config.toml. Set them on the UI process. The UI then opens one server span for each page, data and resource request. Each Coral gRPC call the request makes joins that trace. Send the UI and Coral to the same backend to see one trace for each UI request. The UI also opens a span for each loader and action, and a client span for each Coral call. Coral’s server span for a call is the child of its client span. UI spans carry the method, the route template, the status and the kind of a failure. They never carry headers, bodies, query strings, cookies or full URLs. A valid caller traceparent continues its trace, and an invalid one starts a new trace. The UI never reads or forwards baggage or tracestate. /healthz and /readyz open no span. Coral follows the sampled flag on each UI call, so OTEL_TRACES_SAMPLER decides which of these traces Coral exports. When the UI does not export, it forwards only a valid caller traceparent, and Coral follows that caller’s sampled flag. A gRPC call with no traceparent starts its own trace, and trace_sample_ratio decides if Coral keeps it. The UI checks the endpoint, protocol and sampler values only when export is on.

Metrics

With endpoint set, you receive the coral.* metrics below. Their names, units and attributes are stable within a major version. No attribute holds an identifier, a provider name, a tool call path, a client or an endpoint. Durations are in seconds and sizes in bytes. Gauges show the value when Coral collects metrics, every 5 seconds.
  • On coral.request.duration, operation is the route template or the gRPC method. An MCP tool call is tools/call followed by the tool’s name, such as tools/call exec.
  • On coral.run.claims, operation is the claim: accept, start, recover or takeover.
  • coral.run.queue.depth counts the program runs on this Coral instance that are accepted but not started yet. A run starts right after it is accepted, so this is usually 0. A run that waits for recovery by another Coral instance is not counted.
  • coral.program.execution.heap.peak is sampled each time a program waits and when it ends. A program that frees memory before it waits or ends shows less than its true peak.
At most 2048 spans and 2048 log records wait for export. When a queue is full, the next span or log record is dropped and counted in coral.telemetry.dropped with drop.reason queue_full. A failed export counts its spans and log records with export_failed. Neither delays a request or a program run. Metrics are cumulative by default, so a failed export loses no metric points: the next export carries their totals. If you select delta temporality, the metric points of a failed export are counted too. If you see drops, check that your collector is reachable and keeps up.

Concurrency bottlenecks

Use these signals together to separate database admission, compiler saturation, search projection lag, and direct request CPU. Database acquisition. operation identifies begin_write, begin_read_snapshot, execute, fetch_optional, fetch_all, or ping. Acquisition duration covers the wait for a pooled connection. For transaction entry points, it also includes BEGIN. Direct-query execution is excluded. Outcomes are ready, failed, or canceled. A query failure after acquisition does not count as an acquisition failure. Transaction duration starts after acquisition. The waiter gauge counts callers awaiting acquisition; a detached Postgres BEGIN can finish after its caller cancels. Compiler. compiler.role distinguishes the Run compiler (run) from the Saved Function compiler (authoring). Each has one worker and 32 queue slots. Check depth, active work, waits, and outcomes by role. operation identifies program, saved_function, or analysis. Request duration includes queueing and ends when the caller receives an answer. Outcomes distinguish queue_full, stopped, timed_out, rejected, failed, and ok. Queue depth includes enqueue attempts until they succeed or fail. An accepted job remains queued after its caller times out until the worker dequeues it. Work duration starts at dequeue and includes expiry checks. When a compile throws, is stopped, or exceeds its heap, the worker replaces its isolate before the next request. When the isolate grows too large, the worker replaces it too. Isolate build duration measures each replacement. build.reason is fault, recycle, or retry. retry means an earlier replacement failed, so a request built the isolate. A rising fault rate means compiles are throwing, reaching their deadline, or exceeding their heap. Read the request outcomes to tell these apart. coral.program.compile.duration still covers Program admission only. Its outcomes are ok, rejected for a Program Coral refused, timed_out, and unavailable for a busy, stopped, or failed compiler or a failed database read. Search backlog. search.projection.kind distinguishes Provider catalog projections (provider_catalog) from Saved Function projections (saved_function). These are units of indexing work, not counts of searchable Tools. Backlog includes missing or stale projections and failed retries that are not due yet. An observer runs in a separate supervised task, with shared shutdown, and takes read-only snapshots every 30 seconds. Each snapshot read has a 30-second limit. Failure logs identify the task and safe failure kind. A panicked task restarts after one second without stopping the other task. Check sample.age before trusting a count. A failed read reports no snapshot. A stopped observer removes its observation rather than reporting its last count. First visibility and recovery. first_visibility.age covers only published Provider catalogs that have never been searchable. Renames and index-version rebuilds do not reset first visibility. The age is zero when none are waiting and absent when visibility history or the clock is unknown. Legacy failed projections can have unknown history; no first-visibility latency is invented for them. publication.visibility.duration runs from the stored publication timestamp to the first successful index commit, including the publication transaction. initial identifies a first-attempt success; retried identifies success after failed initial attempts. Rewriting a complete projection records no visibility duration. If a previously searchable catalog becomes unavailable after a failed rebuild, index.recovery.duration measures from the first recorded failure to the recovery commit. Repeated failures preserve that start time. Visibility history survives restarts. Samples for replaced catalogs or failed visibility checks are omitted. Verification runs separately from index writes. The duration ends at the commit and excludes verification time. These signals exclude client setup time. Request CPU. On Linux and macOS, CPU samples bracket each poll of the request handler and response body. Synchronous work in inline-awaited futures is included. Pending wait time, spawned tasks, and dedicated compiler or Program execution threads are excluded. The metric uses the same operation and outcome as request duration. Traces carry coral.request.cpu_ns, including when a handler is canceled. Sum CPU seconds by operation to attribute direct request work; this is not total process CPU. CPU histogram boundaries start at 10 microseconds and include sub-millisecond ranges. Other platforms omit the CPU signal.

Auth

[auth]

[auth.session]

Refresh tokens

Coral gives a refresh token with each access token to a client that lists refresh_token in its grant_types. This applies to registered clients and to clients with a Client ID Metadata Document. Other clients get access tokens only.
  • Lifetime. Your users can refresh for refresh_token_ttl_seconds after they sign in. A refresh does not extend this time. When it ends, your users must sign in again.
  • Single use. Each refresh returns a new refresh token, and the old one stops working. If a client sends a used token again, refresh stops for that sign-in, also for the newest token. Your clients must not refresh with the same token twice at the same time. If a refresh response is lost, the user may have to sign in again.
  • Current access. Each refresh checks that the user is still an enabled member of the organization. For a workspace token, it also checks that the user is still a member of the workspace. A refresh does not contact your OIDC issuer. Changes you make at the issuer apply at the next sign-in. If you remove a membership, refresh stops for good, even if the user joins again.
  • Revocation. To revoke a refresh token, send token and client_id to <listeners.auth.public_url>/oauth/revoke. A client registered with client_secret_post also sends its client_secret. Revocation stops refresh only. Access tokens that Coral already issued work until they expire. To cut off a user at once, disable or remove their organization membership: Coral then refuses their access tokens on the next request.
  • Storage. Coral stores only a SHA-256 digest of each refresh token, in its database. Refresh tokens survive restarts. If you run more than one Coral process, give them the same database so that each process can refresh any token.

Web sessions

The web interface keeps your users signed in through a web session that Coral holds. At sign-in, the web interface gives its refresh token to Coral and keeps only a random session handle in a signed cookie. On each request, Coral mints a new access token for that session, which lasts at most five minutes. Your users stay signed in when an access token expires.
  • Lifetime. A web session lasts CORAL_WEB_SESSION_MAX_AGE_SECONDS (default 2592000, 30 days) or until refresh_token_ttl_seconds ends, whichever comes first, and never longer than one year. Activity does not extend it. To keep users signed in longer, increase both values. To sign them out sooner, decrease the value that limits the session, or both.
  • Several processes. Every web interface process reads sessions from Coral. You do not need shared storage for the web interface itself. Give every Coral process the same database and the same session signing key, and every web interface process the same CORAL_WEB_SESSION_SECRET, so that each process can finish a sign-in and serve a session that another one started.
  • Sign-out. Signing out ends the session and its refresh token at Coral, and a copied session cookie stops working. Access tokens that Coral minted for the session before sign-out work until they expire, within five minutes.
  • Sign-out when Coral does not answer. The browser still signs out. The next visit to the sign-in page finishes the sign-out at Coral. Until then, a copied session cookie still works, at most until the session would end.
  • Outages. If Coral does not answer, the web interface shows an error and keeps the session. Your users stay signed in when Coral recovers.

[auth.provider]

Register <listeners.auth.public_url>/auth/oidc/callback as the redirect URI at the OIDC issuer.

[auth.provider.access_token]

Optional section that can be used to require certain values on the OIDC’s access token.

Database

[database]