# App configuration

> The cross-cutting settings an app declares in one place — the app config object. Two kinds live here: the external providers and credentials your app depends on (secrets, OAuth clients, an embedding provider) and the app-wide policies (data classifications, audit-trail access, an MCP tool surface). Each is one typed declaration.

<!-- id: config-index · area: config · stability: stable · html: https://osysharp.com/reference/config/index/ -->

## Summary        {#summary}
Some things belong to the **whole app**, not to any one entity or function: the API keys it needs, the OAuth providers
it signs users in with, the model it embeds text with, the sensitivity policy over its data. Those are declared once,
as typed properties on the app config object, so there is a single place to look and the compiler checks each one.

They fall into two groups: **what the app depends on** (secrets, OAuth clients, an embedding provider) and **policies
over the app** (classifications, audit access, an MCP surface).

## Description    {#description}

### What the app depends on   {#dependencies}
- [declaring secrets (app.Secrets)](https://osysharp.com/reference/config/secrets/) — `app.Secrets` declares the named secrets the app uses (API keys, tokens, client secrets). Each
  is `new Secret("Name")`; a value is never inlined in source. Mark one `{ UserScoped = true }` for a per-user secret.
- [OAuth clients (app.OAuthClients)](https://osysharp.com/reference/config/oauth-clients/) — `app.OAuthClients` declares the third-party OAuth providers, both for signing users in
  and for calling an external API on a user's behalf.
- [embedding provider (app.Embedding)](https://osysharp.com/reference/config/embedding/) — `app.Embedding` names the embedding model that turns text into vectors, which is what powers
  semantic search over `[Searchable]` fields.
- [per-environment config (app.Config)](https://osysharp.com/reference/config/app-config/) — `app.Config` declares the app's per-environment settings (`new Setting("Name")`), read
  anywhere as `Config.Name`; each environment supplies its values from a checked-in `.env.<mode>` file. Non-secret
  configuration — the counterpart to `app.Secrets`.

### Policies over the app   {#policies}
- [data classifications (app.Classifications)](https://osysharp.com/reference/config/classifications/) — `app.Classifications` maps a data-sensitivity level (a `DataClass` — PII, Financial,
  Secret, …) to the `[Role]` members allowed to read fields marked at that level. You declare the mapping once; fields
  opt in with a classification attribute.
- [audit read access (app.Audit)](https://osysharp.com/reference/config/audit/) — `app.Audit` declares who may read the app's audit trail. The platform records entity changes
  automatically; this gates the reading of that record.
- [workflow run retention (app.Workflow)](https://osysharp.com/reference/config/workflow/) — `app.Workflow` declares how long FINISHED workflow runs are kept. Undeclared, a completed run
  is kept for ever with everything it owns; a window reaps it, and a run still in progress is never reaped whatever
  its age. It is also a ceiling on how long [audit read access (app.Audit)](https://osysharp.com/reference/config/audit/) can keep the workflow transition trail.
- [MCP tool server (app.McpServer)](https://osysharp.com/reference/config/mcp-server/) — `app.McpServer` exposes the app to an MCP client (an AI agent) as a set of tools, grouped
  into catalogs, each with its own visibility.

### UI surfaces the app owns   {#ui}
- [UI surfaces (app.Ui)](https://osysharp.com/reference/config/ui/) — `app.Ui` nominates the app's own components for the *system surfaces* the platform would otherwise
  draw a bare fallback for: `ConnectionSurface` (the server dropped — see [Connection](https://osysharp.com/reference/ui/connection/)), `NotFoundSurface` (404),
  `ForbiddenSurface` (403), and `ErrorSurface` (an unexpected load failure).

### One object, checked at compile time   {#compile-time}
Because each of these is a typed declaration rather than a config file parsed at boot, a missing provider, a
misspelled role, or a secret that no code reads is caught when the app compiles — not in production. The
[`use`](https://osysharp.com/reference/types/use/) declaration is the companion in the manifest: `use` brings a capability's tables and types into
the app; the config object here tunes how the app uses them.

## See also       {#see-also}
- [declaring secrets (app.Secrets)](https://osysharp.com/reference/config/secrets/) · [OAuth clients (app.OAuthClients)](https://osysharp.com/reference/config/oauth-clients/) · [embedding provider (app.Embedding)](https://osysharp.com/reference/config/embedding/) — the app's external dependencies
- [data classifications (app.Classifications)](https://osysharp.com/reference/config/classifications/) · [audit read access (app.Audit)](https://osysharp.com/reference/config/audit/) · [MCP tool server (app.McpServer)](https://osysharp.com/reference/config/mcp-server/) — the app-wide policies
- [use](https://osysharp.com/reference/types/use/) — declaring a capability the app depends on