AI studio

Mastra Studio, the local dev UI for inspecting the assistant agent, its memory threads, and its traces.

Mastra Studio is a local web UI that opens against your real assistant - the same agent, prompt, model and Postgres-backed memory the app serves. It is a development tool only: nothing about it is bundled, deployed, or reachable from the running app.

Launch it

Start the local infrastructure so Postgres is up: pnpm infra.

Confirm DATABASE_URL is set in the root .env.

Run pnpm mastra:studio from the repo root.

Open the printed URL - http://127.0.0.1:4111 by default.

Open 127.0.0.1, not localhost. Studio bakes 127.0.0.1 into the page as its API base, so a localhost tab is a different origin: the UI loads and every request it makes fails with Failed to fetch.

pnpm mastra:studio

It runs on its own, not as part of pnpm dev. With config.ai.enabled false it prints one line and exits - there is no AI surface for it to inspect.

What you can see

Surface	Shows
Agents	The assistant's resolved instructions, model, and tools
Chat	A playground that runs the agent for real, against your dev database
Memory	Stored threads and messages, the same rows the chat surface reads
Traces	Agent and tool spans, when observability is configured
Logs	Server-side run logs

How it binds to your app

The entry file is packages/api/src/mastra-studio/index.ts. It exports the instance built by getMastra(), so Studio inspects the real agent defined in packages/api/src/mastra/agents/assistant/config.ts - edit the persona there and Studio reflects it on reload.

It runs as its own process on its own port. It does not mount into the Hono API, so no route is added to the app and no production build changes.

Security

Studio requires NO authentication - anything that reaches the port can run your agent and read its memory. Never expose or deploy it.

pnpm mastra:studio pins MASTRA_HOST=127.0.0.1 (the bind) and HOST=127.0.0.1 (the URL the CLI prints), so Studio is reachable from your machine alone. Set MASTRA_HOST yourself only if you need otherwise - a phone testing against your dev box, or a container.

That pin is load-bearing. Left unset, the mastra dev server binds every interface, your whole LAN included, while still printing a localhost URL - so the exposure does not show up in its own output.

Notes

mastra is a devDependency of @repo/api, so a production install with --prod never pulls it.
The bundle it builds lands in the gitignored packages/api/.mastra/.
Writes are real. Chatting in Studio persists threads to your dev database exactly as the app would.

AI

The AI surface itself: models, metering, chat, and automated runs.

AI agents

The assistant agent, its tools, and how to add your own.