# Core configuration

> Field reference for the configuration shared by every LLM Surface and IDE Surface.

Every surface, LLM or IDE, is backed by the same stored configuration record. It carries the surface’s identity and routing, plus a set of optional configuration blocks, each covered by its own reference page. Nothing is mandatory: a surface with no optional blocks configured behaves as a thin, low-latency proxy to its provider. See [Surfaces →](/products/affinidi-trust-fabric/agent-stream/concepts/surfaces.md) for the conceptual model.

In the dashboard’s surface builder, a surface opens on a canvas with two connected, configurable nodes: an Access Point node (the listener and route) and an LLM node (the provider, model, and credentials). A separate, non-configurable Caller node represents the calling client itself. Optional capabilities are added as further canvas elements on the edge between the Access Point and the LLM node.

## Identity and lifecycle

Every surface carries a stable identity and a simple on/off state, independent of whatever else it’s configured to do.

| Field | Required | What it does | Default |
| Surface ID | Read-only | Unique identifier assigned at creation. Never changes. | Auto-assigned |
| Name | Yes | Human-readable name. Appears in the dashboard, logs, and metrics. | — |
| Description | No | Optional free-text description. | — |
| Surface Enabled | No | In the dashboard this is a single checkbox, labeled Surface Enabled on an LLM Surface, IDE Surface enabled on an IDE Surface, that flips the surface between enabled and disabled (an unchecked surface shows a DISABLED badge). Deleting a surface removes it from active routing and hides it from listings, but the record is retained so historical usage attribution survives. | On |

## Listener and routing

Where a surface listens for traffic, what path it answers on, and which client wire formats it accepts.

- Most surfaces just use the shared listener and path defaults. Set Listen Address and Route only when you’re deliberately placing this surface on its own network binding or path.

- Keep both Client API Formats on unless you want to lock a surface to a single client dialect, for example a surface that should only ever be called through the Anthropic Messages shape.

| Field | What it does | Default |
| Listen Address | The network binding this surface’s Caller node listens on. | Not set |
| Route (dashboard: Path prefix + Custom path) | The URL path this surface answers on, combined with the listen address to form the full route callers send requests to. Not typed as one field in the dashboard: the Caller node’s Path prefix dropdown and Custom path text input compose it, and the result is shown read-only in a Pipe Route banner (IDE Route on an IDE Surface). | Not set |
| Client API Formats | Client wire formats this surface answers, picked from a list of per-format toggles (OpenAI Chat Completions, Anthropic Messages, OpenAI Responses). The inbound format is negotiated per request by path (/v1/chat/completions = OpenAI Chat Completions, /v1/messages = Anthropic Messages) and normalized to one canonical shape before the request enters the pipeline; the response is re-skinned back to match. | Both OpenAI and Anthropic |

### Identity pass-through

Forwards the caller’s own validated bearer token to the provider instead of the surface’s stored API-key secret. Some upstreams need to know which signed-in user is calling (an Azure OpenAI deployment secured with Microsoft Entra ID, for example), so answers and access stay grounded in that person’s own identity rather than a shared service account.

- Leave this off for a normal shared-credential surface; the stored API-key secret is simpler and is what most providers expect.

- Turn it on when the upstream needs the caller’s identity: Azure OpenAI with Entra ID, or any other Bearer-accepting upstream.

- Requires JWT-bearer source authentication first, since the forwarded token must be validated before it’s passed on. Variant-overridable.

| Field | What it does | Default |
| Forward caller’s token to the provider | Forwards the caller’s validated inbound bearer token as the outbound credential instead of the surface’s stored API-key secret. In the dashboard this is a switch labeled “Forward caller’s token to the provider (identity pass-through)” under an Identity pass-through section. | Off |

## Surface type

The dashboard offers two kinds of surface, each with its own creation flow and its own page in the sidebar.

| Surface type | What it does |
| LLM Surface | The default and most common choice: one configured LLM provider. See [Providers →](/products/affinidi-trust-fabric/agent-stream/reference/surfaces/providers.md). Its API path (used by the sandbox and internal calls) falls back to /v1/chat/completions when not otherwise configured. |
| IDE Surface | Works differently: a governed, per-caller-filtered model-discovery menu that aggregates other surfaces, rather than fronting a single provider itself. See [IDE Surfaces →](/products/affinidi-trust-fabric/agent-stream/reference/surfaces/ide-surfaces.md). |

## Optional configuration blocks

Beyond identity, routing, and the provider itself, a surface can add further optional capabilities: guardrails, content-based routing, failover and caching, cost and usage limits, team attribution, source authentication, OPA policies, governance recording, drift detection, and server tools and modalities. Each is off by default and documented on its own page. See [Surfaces reference →](/products/affinidi-trust-fabric/agent-stream/reference/surfaces.md) for the full list.

One of these has no page of its own: Max reasoning tokens (per request) caps how many reasoning (“thinking”) tokens a provider can spend on a single request. When set, a caller’s requested reasoning budget is clamped to this value and the effort level is lowered to match. It’s unset by default, so reasoning is uncapped, and lives in the dashboard as a numeric field under a Reasoning Budget Governor card on the LLM config editor.

## Integrations

Integrations (Slack, email, webhook, …) can be triggered on surface events such as an execution completing, an execution failing, or a budget threshold being reached. Each mapping names the integration to notify, which events trigger it, and any template variables to pass along. See [Notifications and alerts →](/products/affinidi-trust-fabric/agent-stream/reference/observability/notifications-and-alerts.md) for the full event-type taxonomy.

## Sandbox sign-in

When a surface has Forward caller’s token to the provider (identity pass-through) turned on, testing it from the dashboard’s Sandbox tab needs a delegated caller token to send. This field tells the Sandbox tab which identity to sign in as for that testing.

The Sandbox Sign-in picker only appears in the Sandbox tab’s header when at least one of these is true: this surface has identity pass-through on, your organization has at least one OAuth Identifier profile set up under Credentials → OAuth Identifiers, or this surface already references one. If none of those apply, the picker doesn’t show at all, and the Sandbox otherwise works normally without it.

| Field | What it does | Default |
| Sandbox Sign-in | Reference to an OAuth Identifier profile (Credentials store) used as the surface’s sandbox sign-in identity. Set this to whichever OAuth Identifier profile represents the account you want the Sandbox tab to test as. | Not set |

## Related

- [Providers](/products/affinidi-trust-fabric/agent-stream/reference/surfaces/providers.md): Every supported LLM provider and its fields.

- [Guardrails](/products/affinidi-trust-fabric/agent-stream/reference/surfaces/guardrails.md): Prompt Guard, Expert Witnesses, Judge, and Jury field reference.

- [Routing and variants](/products/affinidi-trust-fabric/agent-stream/reference/surfaces/routing-and-variants.md): Decider, canary, routing rules, and the variant catalogue.

- [Surfaces concept model](/products/affinidi-trust-fabric/agent-stream/concepts/surfaces.md): How surfaces work at runtime.

- [Notifications and alerts](/products/affinidi-trust-fabric/agent-stream/reference/observability/notifications-and-alerts.md): The event-type taxonomy behind a surface’s Integrations mappings.