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.

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#

What the app depends on#

declaring secrets (app.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) — 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) — 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) — 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#

data classifications (app.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) — 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) — 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) can keep the workflow transition trail.
MCP tool server (app.McpServer) — 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 surfaces (app.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), NotFoundSurface (404), ForbiddenSurface (403), and ErrorSurface (an unexpected load failure).

One object, checked at 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 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.