courier.config.ts

Overview

courier.config.ts, at the project root, names the project's API sources and what the tools around them need. defineConfig types it:

import { defineConfig } from "@noverax/courier/config"
import { api } from "./api/sources"

export default defineConfig({
  sources: { api },
  studio: { port: 6280 },
  server: { allowedOrigins: ["https://app.example.com"] },
  runtime: { appOrigin: "http://localhost:3000" },
})

Studio reads it, and so do the Studio runtime (attachRuntime()) and the standalone server (courier-server) — both of which run in production. So the file imports nothing meant only for development: mock servers are declared in courier.mocks.ts beside it, which only Studio reads — see Mock Servers.

The file may also be named courier.config.mts, .cts, .js, .mjs or .cjs, looked for in that order after .ts. How Studio Loads the Project says which files Studio watches and how a change reloads them.

sources

Required. The sources the project serves and calls, by the name its callers use: sources: { api } is reached as createProxyCaller<typeof api>("api"). A project without an API yet starts with sources: {}.

imports

The API specifications Studio imported, by key. Studio writes an entry when it imports a specification and reads it on every re-sync, so an entry is usually Studio's to write; editing one by hand is supported.

See Import an API.

studio

What Studio reads: port, host, mockBasePort and open when it starts, and allowedSpecHosts whenever a fetch would reach a private host. A value Studio cannot use — a port that is not a whole number from 1 to 65535, an empty host, an open that is not true or false — fails the config, and its error names the field.

server

What the standalone server reads when its command-line flags say nothing.

runtime

What attachRuntime() needs in the application's process.

agents

What the project offers to AI agents as MCP tools. The server in your editor, Studio and courier-studio diff read it here; an application's own MCP endpoint takes it as createMcpHandler({ agents: config.agents }). Left out, the endpoints marked .agent() are offered and nothing else.

A pattern names an endpoint by its call under its source; * stands for any part of one name, ** for any number of names. A key or a value the policy does not know stops the MCP server with AGENT_POLICY_INVALID — a misspelt key under agents is named when Studio loads the config, too. See What agents may call.