# Studio A development server with a web UI: inspect requests, explore endpoints, call them from a playground, and run mock servers. ## Overview Courier Studio is a development server with a web UI: a request inspector, an endpoint explorer, an API playground, mock servers, and more. You run it next to your app, and your app connects to it — the server side through `attachRuntime()`, the browser side through one of the build integrations below. In the inspector, a call's answer and its variables show as a tree or as text. **Find** searches their keys and values: the tree keeps what matches and what holds it, opened, with the text marked; the raw text marks its lines; Enter and Shift+Enter move from one match to the next. A body larger than 16 KB shows in part, each part left out named where it was, and **Find** searches the whole of it, which the app or the mock keeps: what the parts left out hold shows too, the raw text's lines numbered as in the whole body, and the line under the field says how much it found — or, once the whole is no longer kept, that the search covers the part shown, and why. Each row of the tree copies the path code reaches it by, such as `data.cities[41].name`, and the headers' filter marks what it finds. A request that got no answer shows why, as the platform said it. Its **Error** tab puts the code in its badge — a system's, such as `ENOTFOUND`, `ECONNREFUSED` or `DEPTH_ZERO_SELF_SIGNED_CERT`, Bun's `ConnectionRefused`, or Courier's own `TIMEOUT` for a request whose `timeout` ran out — and the text under the message, each said once: no badge repeats the error's kind, and no line what the message already says. The raw error carries both as `cause`, the **Overview** lists them as its **Cause**, and the **Response** tab — the Playground's too — says there was no answer, with the code and the text, rather than that the server answered with an empty body. The suggested fix follows the code: a host name that did not resolve, a connection that failed, a certificate that was not trusted, an answer that broke as it arrived, an API that sent no headers in time, redirects that never reach an answer; a code it has no advice of its own for gets the general one and is named in it. A browser's fetch gives no code and says only that it failed — `Failed to fetch` in Chrome, `Load failed` in Safari, `NetworkError when attempting to fetch resource.` in Firefox — and a request refused by CORS fails the same way, so the fix says what else it can mean. A call made through the proxy shows the cause the server met, as the server's side of the call reports it; the browser is told no more than before. A request a middleware failed because a connection of its own was refused, as a `fetch` for a token can be, shows the code and the text the system gave it too. A stream whose connection cannot be made says so, rather than standing open and live: its **Messages** tab and its **Overview** say it is reconnecting, why its last connection ended — the platform's code and text, the status a server refused it with, a server that fell silent, or how a socket closed — how many connections in a row failed and when the next one opens, and its handshake reads *never opened*. The Timeline and the other lists say *retrying* — and, while its first connection is being opened, show it waiting as a request in flight — and the [editor's hints](/docs/studio/editor) count the streams reconnecting apart from the ones open. A stream that gives up before any connection opened says so, with the code and the fix it usually needs. A browser's WebSocket, and Node's own, tell no more than the close code `1006`: why the socket failed is theirs to keep, where a socket of the `ws` package gives the system's code and text. A stream or a channel the proxy relays tells how its upstream connection stands. One served in process opens no connection and stands open, as does every stream of an app on an older Courier. An ended stream says who closed it — its server, its caller, its lifetime, a server that shut down — and, closed while it was reconnecting, why its last connection ended. The Playground starts an endpoint with variables its schema takes, read from the schema itself — Zod, Valibot, or any schema with a `toJsonSchema()` such as ArkType's: a number at zero or at the bound nearest it, a string of its least length, an enum's or a literal's first value, the first option of a union its schema takes, a sample of a known string format — an email, a URL, a UUID, a date and a time, an IP address — and a nested object filled in the same way, three levels down. A field whose schema checks more than Studio reads — a pattern, a refinement, a `Date`, which JSON does not hold — is left out when it may be, and starts as the nearest value of its kind when it is required. A variable the endpoint's `.defaults()` fills in starts at its default. A call whose variables the input schema refused says so where its answer would be: its **Response** tab — the Playground's too — says it was not sent and what the schema said of the first field it refused, and its **Request** tab marks each one. The Playground's status reads *variables refused*, the line under the variables keeps the refusal until they change, and the toast says the input schema refused the call rather than that a request failed. ## Install > **In one command** > > `npx @noverax/create-courier` sets Studio up with the rest: both packages, the integration for your framework, a mock API to work against, and a `studio` script to start it with. See [Create Courier](/docs/create-courier). By hand: ```bash npm install --save-dev @noverax/courier-studio npm install @noverax/courier-studio-core ``` Studio needs Node.js 22.13 or newer. Studio is a development tool, so it is a dev dependency. `@noverax/courier-studio-core` is what your server instrumentation imports `attachRuntime()` from, so it is a dependency: a production install leaves dev dependencies out, and a server that imports the runtime does not start without it — even one that calls it only in development. `attachRuntime()` runs in production too, where it registers the config's sources. An app that only connects its browser through a build integration can leave it out. ## Start Studio ```bash npx @noverax/courier-studio ``` Studio listens on `http://localhost:6280` — at both `127.0.0.1` and `::1`, so it answers whichever one a client dials — or on the `studio.host` and `studio.port` of your `courier.config.ts`. Server runtimes and the build plugins read the same block, so moving Studio there moves them with it: a server runtime reads the nearest config at or above its working directory, and a build plugin the nearest at or above Vite's root — or, for webpack, esbuild and Rollup, the working directory. Flags: `--port`, `--host`, `--cwd` (project root), `--dotenv` (the `.env` files to read, instead of the project's [development set](/docs/studio/project-loading#loading)), `--open` (open a browser), `--version`. Studio writes the [routes module](/docs/proxy-mode/expose) a page's proxy client takes each time it loads the config; [`courier-cli routes`](/docs/proxy-mode/expose#review-it-as-a-permission) writes it without Studio, and checks it in CI. Its commands run without the server: `courier-studio openapi` writes the sources as [OpenAPI documents](/docs/advanced/openapi), `courier-studio verify` checks [recorded calls](/docs/testing/recorded-tests) against the definition, `courier-studio diff` reports what a change to the definition [breaks for its callers](/docs/testing/breaking-changes), and `courier-studio mcp` serves Studio to [an editor's agent](/docs/agents/studio). Studio keeps its working files — imported API state, copies of the files it replaced or removed, saved sessions — in `.courier/`, which ignores itself in git. What Studio shows is kept in `.courier/studio.db`, a SQLite database built into Node, with nothing to install or set up. The requests it captured are there, the latest 2000 of them, so a page that reloads, or a Studio that restarts, shows them again. A request still open when Studio stopped is shown as ended, since no runtime can say any more how it ended. The saved sessions are there too, and which one a page loaded: a page that reloads shows that session again, recording paused, until you go back to the live requests with the play button or **Back to live requests** in the command palette. A session shared as a [session file](/docs/studio/session-files) opens in a colleague's Studio the same way. So are the requests each mock answered, the latest 500, which the Mocks view's log shows again, and the Playground's history of calls. So is what you set, and what you leave unfinished: the settings; the requests you pin, which the log keeps as it lets its oldest go; the Playground's drafts; Get started's progress; a mock wizard or an API import left midway, which opens again where it was; and the network conditions and the scenario set on each mock, which it has again when it starts again — unless the mocks file now declares other network conditions, the newer word. All of it is kept for the project, so another browser shows it too; a page opened without the token sees it but keeps its own changes to itself. The browser keeps only the page's token, and a copy of the settings so the page opens in its theme before Studio answers. Studio creates the file readable and writable by its owner only. **Settings → Storage** shows the room each part of `.courier/` takes — the database on disk and the data in it, the captured requests, the mocks' logs, the Playground's history, the saved sessions, the mocks' stores, and the backups of the files imports replaced — and clears any of them, or all at once, after asking. A mock that runs resets its store to its seeds; the backups an undo still needs stay. The database gives the room its deleted rows took back to the disk as it goes, and is compacted after each clear, so it does not keep growing as the logs let their oldest requests go. Once it grows past the size set there, 500 MB to start with, a line under the header says so. To start empty, clear everything there — or delete the file with Studio stopped. No credential is written there. The value of `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie`, and of any header whose name has a word such as `auth`, `token`, `secret`, `password`, `session`, `csrf` or `api-key` in it, is kept as `[redacted]` in the request log, the mocks' logs, saved sessions and the Playground's history, and so in a HAR or Postman export of a session. The live view, which nothing writes down, shows the values whole to a page opened from Studio's link, and redacted to any other; a request replayed after a reload carries `[redacted]` instead. The texts that could hold one are kept the same way. The page opened from Studio's link — the one that holds its token — shows each as your app was told it: an error's text and its cause, a stream's and a middleware's, what the Playground was answered, a request's address. What leaves that page has the credentials in them cut: what Studio writes in `.courier/studio.db`, a saved session and what it exports — a HAR, a Postman collection, a [session file](/docs/studio/session-files) — what [an agent](/docs/agents/studio) is told, and what a page opened without the token is shown. Cut are an address's user and password, its secret parameters and a path segment that reads as a token; a `user:password@` before a host; a header value the platform quoted; a JWT or a provider's key, such as `ghp_…`, `sk_live_…`, `AKIA…`, `xox…`, `npm_…` or `SG.…`; a credential after `Bearer` or `Basic`; and the value of a pair named as a token, a key, a secret or a password. A word is cut only when it reads as a credential, so `Token expired` and `tokens: 3 of 5 used` stay as they are; a `user:password` with no host after it and no word of signing in around it is not recognized. Only the start of a long text is read, so a text of any size costs the same. Your app cuts nothing and carries no code for it: it tells Studio what it was told, and Studio cuts what leaves. A body larger than 16 KB, sent or answered, is kept and shown as a part of it: the first items of a list, the small fields of an object and a part of each large one, the start of a text, each part left out named where it was, as `"… 45,800 more items"`, beside the size of the whole. **Download whole** in the request's Response or Request tab saves the whole body as a file, from the app or the mock that holds it: each keeps the whole bodies of its latest requests, up to 64 MB, a page in the browser up to 16 MB. A replay sends the whole variables, never the part, and is refused once they are gone; a snippet of a request whose body is too large to write out sends it from the file **Download whole** saves. A saved session keeps the parts, and its HAR and Postman exports say how large each whole was. A page that connects is sent each log's newest requests, each whole, as many as fit 16 MB. When the database cannot be kept there — `.courier` is a link, the disk is read-only, a newer Studio made it — Studio keeps its data in memory for that run, and says so. A file there that is not a database is moved aside to `studio.db.broken-