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 through the proxy as createProxyCaller(apiRoutes), from the routes Courier writes for it. 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, allowedSpecHosts whenever a fetch would reach a private host, and routes each time the config loads. 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, a routes path outside the project — 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.

How the app learns its origin

In development, with no appOrigin, COURIER_APP_URL or APP_URL, the app learns its origin from the server itself, never from a header a request sends, so a reverse proxy, a tunnel, a container or a *.localhost name in front of it needs no setting:

• Next.js, a Hono app inside a Next.js route among them: the address next dev records as it starts listening, https only with its own certificate, before any request.
• Express, Fastify, NestJS, Hono on Node or Bun, SolidStart: the address and port of the socket the first request to a Courier route arrived on. Until a Courier route has served a request, a Playground call has nowhere to go: open a page that calls your API first.
• The standalone server: the address it listens on, as it starts.
• SvelteKit, Astro, React Router, Nuxt: the address Studio's Vite plugin or Nuxt module sees the dev server start listening on, before any request. Under an app's own server that runs Vite in middleware mode, as React Router's custom server does, the socket of the first request that server hands Vite.

Set COURIER_APP_URL where Studio cannot see the server — Deno, Cloudflare Workers, a server on a UNIX socket, or an app that routes by the name it is reached at — to the address the app's own process reaches its proxy route at: in a container, the container's own address and port, not the port the host publishes; behind a tunnel, the local address, not the public one, which would send the Playground's calls and their credentials through the tunnel's provider.

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.