Skip to main content
It is a separate npm package, lousho-studio — the SDK (lousho) does not contain it. One Studio server shows every agent you have: the spec-v2 graph agents saved in your project folders, code agents Studio finds by scanning a workspace, and agents running anywhere that report to the observe collector. This page covers installing and starting Studio, workspaces, which SDK runs a workspace’s agents (and what each banner means), the collector, and how agents deployed on other machines show up here. Using Studio covers the builder, the playground, traces and the rest of the app; the builder, Author and lifecycle screens have their own pages: the visual builder, the Agent Author and versions, triggers and publishing.

Install and start

Any of these works:
Or, inside a project that already has lousho installed, the SDK’s launcher finds the installed Studio and opens this folder as a workspace:
When no Studio is installed the launcher says so instead of bundling one:
lousho studio accepts --port and --host and passes them through; run lousho studio --help for its options. --prod and --dev only apply inside the SDK’s own repository checkout (see Dev mode). lousho-studio (and npx lousho-studio) take the same flags: The server prints its URL, http://127.0.0.1:4750/?token=<random>. The ?token= is a per-launch access token: the page keeps it for that tab and sends it on every API call, so open the printed URL, not the bare host (see Access token). Opening Studio lands on the Agents list (#/agents): your saved agents as cards, plus a New agent menu. Opening or creating one takes you to its Canvas tab — the builder: the build toolbar (the agent’s name and run status, the model badge, then Debug, Stop, Run, Import, Export and Save), the agent rail (your saved agents plus a node/hook palette), the canvas, the Inspector (right), and a bottom drawer with Test, Problems, Logs, Trace, Output, History and Settings tabs. An agent opens with nothing selected and the whole graph fitted in view; the Inspector stays folded away until you select a node, or press the Inspector button at the canvas’s top-right (its accessible name is “Show inspector”), which is remembered. The other screens are one click away in the navigation; see Navigation. Below 860px wide the navigation becomes a drawer opened from the Navigation (menu) button at the top; picking a screen, the scrim or Esc closes it. On the builder the agent rail and the Inspector become slide-over panels you open from the top bar; Run (or Stop) and Save stay in the bar, and Debug, Import, Export and the model badge move into its More actions (⋯) menu.

Workspaces

A workspace is a project folder on disk. The folder you launch Studio from is added automatically; add more with Add workspace → folder path (or the Add workspace… entry in the switcher). The switcher at the top of the nav lists All workspaces, each workspace, and Add workspace…. #/agents is the all-workspaces list; an agent route is #/w/<workspace>/agents/<id>/<tab>. Things live in three places: On first launch after the split, if a workspace still has a project-level .lousho/settings.json or .lousho/secrets.json, Studio offers Import settings and keys from <workspace> once, copies them into ~/.lousho/studio/, and leaves the originals alone.

Three kinds of agent

The all-workspaces agent list mixes three kinds: Observed agents whose collector project matches a workspace id appear under that workspace (see See agents running elsewhere). The rest are grouped under Elsewhere.

Which SDK runs your agents

For each workspace Studio picks how agent processes run:
  • Bridge — the normal case. Studio spawns lousho bridge from the SDK installed in that project (lousho), so runs use the project’s own SDK version. This matters because a project’s { file } tools and skills import that project’s dependencies, which only resolve inside the project.
  • In-process — Studio’s own built-in SDK, used when the project has no SDK installed or its checkout is not built.
  • Read-only — the project’s SDK is too old or speaks a protocol this Studio does not know, so edits are refused until it is fixed.
Each non-default state shows a banner at the top of the workspace’s pages: While a workspace is read-only, writes under its agents (saves, drafts, runs, deploys) are refused; reads still work. A few features still need Studio’s built-in SDK and are unavailable on bridge workspaces:
  • Flow runs: Flow runs need Studio's built-in SDK for now. Remove the project's SDK from this workspace or run the flow from code.
  • Breakpoints: Breakpoints need Studio's built-in SDK for now.
  • Time travel: Time travel is not available yet for projects that run their own SDK.

The collector

Everything under Observe, Evaluate and Assets — and run reporting — reads the observe collector. On boot Studio probes the configured URL (default http://127.0.0.1:7777):
  • Attached — a lousho observe daemon is already running there; Studio uses it.
  • Started — none answered on loopback, so Studio started its own and stops it on exit. It never stops a daemon it did not start.
  • Remote — a non-loopback URL (team or hosted collector); Studio probes it but does not start or stop anything there.
  • Down — nothing answers; daemon screens show the start command instead of data and recover on their own.
The collector card at the bottom of the nav shows the mode (Attached to <url>, Started by Studio on <url>, Remote collector at <url>, Not reachable: <error>). Settings → Collector sets a remote URL and bearer token; create a token with lousho observe token create --project <name>. LOUSHO_OBSERVE_URL and LOUSHO_OBSERVE_TOKEN in Studio’s own environment override the stored setting, and LOUSHO_STUDIO_COLLECTOR=0 stops Studio from auto-starting a local daemon.

See agents running elsewhere

An agent deployed on another machine — a server, CI, a teammate’s laptop — shows up in Studio once it reports to a collector Studio can read. Reporting is pure SDK configuration; nothing in the agent is Studio-specific:
Set these in the deployed environment: Point Studio at the same collector under Settings → Collector (or with LOUSHO_OBSERVE_URL/LOUSHO_OBSERVE_TOKEN in Studio’s environment), and the deployed agent’s traces, scores and sessions appear in Studio’s Observe screens.

Updating

Studio (lousho-studio) and the SDK (lousho) are separate packages and update independently:
A workspace’s agents edit only when the project’s SDK is at least MIN_BRIDGE_SDK_VERSION — the SDK version this Studio was built against. Older SDKs get the read-only banner above; newer ones get the “update Studio” banner. Bridge workspaces also need lousho bridge in the project’s SDK, which speaks bridge protocol 1.

Using Studio

Access token

The studio can store provider keys, start runs and execute hook code, so its API is locked to the browser tab you opened from the printed URL:
  • Each launch mints a random token and prints it in the URL (?token=...). The page keeps it for that tab (it survives a reload) and sends it on every API call (x-lousho-studio-token header) and on the WebSocket (?token= query). A request without it gets 401. Opening the bare http://127.0.0.1:4750 in a new tab loads the page, but its API calls fail until you use the printed URL.
  • The server sends no CORS headers and refuses (403) a request whose Origin is not the studio’s own, or whose Host is not a loopback name (localhost, 127.0.0.1, [::1]) or the --host you bound to. With --host 0.0.0.0 any Host is accepted and the token is the only gate.
  • GET /health and the static client need no token.
From curl, pass the token: curl -H "x-lousho-studio-token: $TOKEN" localhost:4750/agents. lousho studio hands these to the processes it starts through environment variables; you only set them yourself when you start the studio server without the CLI:

Where agents live

Each workspace’s agent specs and run state live under .lousho/ in that project folder (agent YAML files under .lousho/agents/, checkpoints and approvals alongside them) - the same .lousho/ layout lousho dev/lousho build use, so the files travel with the project and stay diffable. Studio-wide state (settings, secrets, the workspace registry) lives in ~/.lousho/studio/ instead; see Workspaces. Those YAML files are Agent spec v2 documents, which that page explains field by field. The Agents screen’s agent rail lists exactly the agents in that workspace’s .lousho/agents/: a YAML file you add there shows up, and an agent you create in the studio is written there at once (autosave and Save both write the file), so it can be chatted with straight away. Another workspace shows only its own agents. The browser keeps nothing but a draft of an edit that could not reach the server (it is pushed on the next load), stored per workspace directory. A file in .lousho/agents/ that no longer parses is skipped with a warning in the server log.

Production vs. dev mode

An installed Studio (lousho-studio, npx lousho-studio, or lousho studio finding it) is always production mode: a single Express server serves both the REST/WebSocket API and the pre-built client (React app) as static files, on one port. There is no separate Vite dev server and no TypeScript loader involved. Dev mode - the API server running from TypeScript via tsx next to a Vite dev server with hot-module reload - exists only inside the SDK’s own repository checkout, for people contributing to Studio itself. There lousho studio --dev (or --prod to force the built bundle) picks the mode; run without either flag it auto-detects based on whether apps/agent-forge/dist-server exists. See Dev mode. The left navigation lists every screen, grouped: Off the builder a page header names the screen and keeps the live run status pill at the end of its title row, after any chips the screen adds (a prompt’s labels, say). Under Settings, a small card shows the collector status (see The collector). The button beside the Agent Forge name at the top of the nav (Collapse navigation) shrinks it to a rail of icons; hover an icon for its name. The choice is remembered across reloads. Below 860px wide the nav is always the full drawer. Every screen has a hash route, and a screen’s filters live in the URL’s query string, so a reload, a bookmark or a pasted link opens the same screen with the same filters. Defaults are never written (a bare #/traces is the default 24 h list). Filter, sort and page edits replace the current history entry, and opening a row pushes one, so the browser’s Back returns from a trace to the list instead of walking through filter edits. An empty or unknown hash goes to #/agents (the ?token= stays). A time range picked from a preset other than the default is written as absolute from/to bounds, so a reload shows exactly the same rows. The full route list is apps/agent-forge/src/screens/routeTable.ts.

Keyboard

The command palette lists Go to every nav screen, Open agent for each saved agent, and Toggle theme (light/dark, remembered in the browser); type to filter. Paste a trace id (8 or more hex digits and dashes) and the first entry is Open trace for it. Arrow keys move, Enter runs. The builder’s own shortcuts — save version, undo/redo, palette search, node delete — are listed in the visual builder. The command palette over the Traces screen In an annotation queue’s review, Enter submits the scores and S skips the item (see Annotation queues).

Status words

Every status in the Studio is the same pill:
  • Runs: ok, error, running, interrupted (the agent’s process died mid-run; see The observe daemon).
  • Agents: healthy, stale (missed heartbeats), down, stopped.
  • Threads: active, ended (idle, see Idle sessions), interrupted.
  • Scores: pass, fail.
  • Builder runs: idle, running, done, stopped, error, awaiting approval.

The collector (observe daemon)

Everything under Observe, Evaluate and Assets reads the observe collector through the Studio server’s /observe proxy, which calls whatever URL the collector manager resolved (see The collector). The proxy forwards reads plus the writes the screens make (feedback scores, new prompt versions from the Playground, prompt label moves, hub entry edits, dataset and example writes, annotation queue writes, evaluator rule writes); every other write, ingest above all, is refused with 405. When a bearer token is configured the proxy sends it to the collector on every read and write (as run reporting and the judge evaluators do), so the screens also work against a collector started with --require-token. Without it, such a collector answers 401 to every /api/ read and the screens show that error instead of data (/health still answers, so the collector card says running). The browser’s own credentials (the Studio token, cookies, Authorization) are never passed on. The collector card at the bottom of the nav shows the resolved mode — Attached to &lt;url>, Started by Studio on &lt;url>, Remote collector at &lt;url> or Not reachable: &lt;error> — and keeps polling. While the collector is down, each daemon screen shows the command to start it instead of an error, keeps its URL, and swaps the data back in by itself once it answers. The Agents screen and Playground runs do not need the collector.

Screens

Agents

#/agents is the agents list: a card per agent in .lousho/agents/, a New agent menu (Blank agent, From template, Describe with AI — see the Agent Author — or Import from file…), and search and label filters. Opening a card goes to its Canvas tab, the builder — see the visual builder and the first-agent walkthrough. #/agents/<id> (the legacy builder URL) redirects to #/agents/<id>/canvas. Leaving the builder with unsaved changes asks first. Runs started there report to the observe daemon, and the Run status pill’s Open trace link opens the run on the Trace screen.

Playground

#/playground (Build > Playground) tries messages against a model without editing an agent: The Playground, loaded from a trace's model call
  • Messages: system, user and assistant message cards. Every {name} placeholder in any message gets a Variables input in the left settings card, in the order the names first appear.
  • Model: a provider (the ones with a key under Settings > Provider keys, plus ollama and mock; mock when nothing is configured) and a model name, sent as provider/model.
  • Tools: pick a saved agent to borrow its tools, then switch each one on or off.
  • Run (or Ctrl/Cmd+Enter in the messages) streams the reply as it arrives; Stop aborts it. Tool calls show as cards that open to their arguments. When the run finishes, the output shows its tokens in and out, latency and cost (when the model’s price is known), and Open trace goes to its trace.
  • Save prompt (in the page header) opens a card whose Save as new prompt version pushes the system message (and its variables) to the prompt registry, under the loaded prompt’s name or one you type. It is disabled while there is no system message.
Two links pre-fill it. Open in Playground on a model call (generation) in a trace opens #/playground?trace=<traceId>&fromObs=<obsId>, which loads that generation’s messages and model. #/playground?prompt=<name>[@<label or version>] (the Prompts screen’s Open in Playground) loads a registry prompt (latest by default) as the system message and records it on the run’s trace. Both read the observe daemon: when it is down, the Playground says so and keeps an empty editor, and runs still work. Runs go through the playground run endpoint and report as agent playground.

Workspaces

#/workspaces lists the workspaces the typed workspaces API knows: name and domain, page count, a Valid/Invalid (n) badge from the workspace’s problems, the live revision and a last-run column (filled in by a later ticket). #/workspaces/<id> opens one workspace with a header that carries the live revision, the problems badge, an Draft open badge while a draft exists, and disabled Run/Chat actions; a left nav switches between the overview, main-agent, pages, agents, runs, improve and revisions sections, the ones not built yet naming their ticket. Every edit is a typed authoring operation sent through ApiClient.call('applyOps', …) into a draft with expectedRevision; the draft is applied or discarded later. When the live revision moved under an open screen the operation gets a 409, the latest revision reloads and a toast says “This workspace changed since you opened it.” The screens call only the workspaces API (/api/workspaces, mounted by a later ticket), through an injected ApiClient, so they run on fixtures today and move to the Next.js app later.

Traces

The Traces list The Traces list in the dark theme The same list in the dark theme (Settings > Appearance, or Toggle theme in the command palette). #/traces lists the daemon’s runs, newest first: status, name, agent, input and output previews, error message, model, start, duration, tokens and cost (narrow windows hide the less important columns). Filter with the search box (name, input or output), the Agent, Status, Model and Project facets, and a time range (15m, 1h, 24h, 7d, 30d or Custom; default the last 24 h). Click Duration, Tokens or Cost to sort by it. 50 rows a page. The page header’s refresh icon (Refresh) re-fetches the list now, and Live (a toggle) refreshes it every 5 seconds until you switch it off or the daemon goes down. A prompt filter (set by the Prompts screen’s “Runs using this version” link) shows as a removable chip.

Trace

#/traces/<trace id> is one run. The header has its name, status, agent (a link to the agent’s traces), model, start, duration, tokens, cost and session (a link to its thread), plus Copy link, Add to dataset, Add to queue and, when the run has a model call, Open in Playground. All traces in the page header goes back to the list. A failed run: the error banner on top of the inspector Below it is the trace viewer the builder’s Trace tab and the queue review also use: the steps as a Tree or a Waterfall (a two-way switch above the steps), and an inspector for the selected step (a failed step is selected by default, else the root). The selected step is ?obs= in the URL. The inspector shows, in order:
  1. Error: the failure message, when the step failed.
  2. Input and Output: messages render as chat bubbles with tool calls as chips; switch between Rendered, Raw and JSON (for JSON content), and copy either block.
  3. Feedback: the step’s scores, and thumbs up / down with an optional comment, saved as a feedback score (1 or 0, source human). On the root step it scores the whole trace.
  4. Tokens, cost and model.
  5. Attributes: the step’s raw attributes as a JSON tree.
Model-call rows carry Open in Playground. Add to dataset copies the run’s input (and output, as the expected value) into a dataset you pick, or a new one you name. Add to queue puts the trace into an annotation queue for review.

Threads

The Threads list #/threads lists sessions: status, session id, agent, last input, turns, start, duration, tokens and cost, filtered by agent, status and time range (default 30 days). A session appears once agent runs carry a sessionId. #/threads/<session id> shows the conversation: every turn (run) oldest first, with its input and output (or error) and an Open trace link.

Monitoring

Monitoring: the fleet over its charts #/monitoring is the “is my fleet up” screen and refreshes itself every 15 seconds. The fleet table lists every agent that has reported: status, last heartbeat, runs today, error rate, p95 latency over 24 h, the reporter’s dropped-event count and a link to its traces. Below it, pick a window (1h, 24h, 7d, 30d) and an agent, and read five charts: Runs, Latency p95 and Error rate (per agent), Cost and Tokens. Click a chart’s bucket to open Traces filtered to that bucket’s time (and agent).

Evaluations

Evaluations in the nav opens #/evals/scores. A sub-navigation at the top of every Evaluations screen (Scores, Datasets, Evaluators, Annotation queues) moves between them.

Scores

Scores, with one eval expanded One row per eval: score pass rate, score count, mean score and last seen, over every score of the eval (its eval-level row per run plus its check rows). Filter by eval, agent, source (eval, judge, human, online) and time range (default 30 days). Click an eval to expand it: the run count and run pass rate, a pass-rate trend, the pass rate of each check (worst first) and the latest failures, each linking to its trace (and step). A score counts as a pass when its value is exactly 1. eval and judge scores (an eval’s assertions and its llmJudge / t.judge() checks, which write a comment only when they fail) also pass when they have no failure comment. human and online scores are decided by value alone, so a 0 (a thumbs-down, a rule that returned 0), a 0.9 or an empty value is a failure. The table and the expanded detail use the same rule. Where eval scores come from: Evals.

Datasets

One dataset's examples #/evals/datasets lists the datasets with their example counts, and has a New dataset form (a name and an optional description). Open one to see its examples (input, expected value, source trace); open an example to see it in full, or Delete it (asks first). Examples come from a trace’s Add to dataset, or by hand through the datasets API. An eval runs over a dataset with defineEval({ dataset: 'name' }) (see Datasets).

Evaluators

The Evaluators list: rules with their switch and last-run counts #/evals/evaluators manages online evaluator rules: rules that score new traces as they finish. Their scores carry the rule’s name and show on Scores with source online. The list shows each rule’s name, kind (code or judge), filter (or “All traces”), sample rate, an Enabled switch (flips the rule on or off at once), and its Last run and Runs (24h), counted from the newest 1000 online scores (a + after the count means that read was full, so the count is a floor). Filter by Kind and State (?kind=, ?enabled=), 50 rules a page. New evaluator opens the form; open a rule (#/evals/evaluators/<rule id>) to edit it in the same form, where Save changes sends only the fields you changed and Delete removes the rule after a confirm (its past scores stay). The form has a name, a sample rate (0-1), an enabled box, the filter (agent, status ok or error, name contains), and the kind:
  • A code rule is a function (trace) => number | { value, comment }, prefilled with a working sample. The observe daemon runs it in its isolate sandbox, so code rules run whether or not the Studio is open (see Online evaluators).
  • A judge rule is a provider, a model and a rubric. The daemon has no provider keys, so the Studio runs judges, with a key stored in Settings or the provider’s environment variable where the Studio runs (the stored key wins); the provider list offers the providers that have either, plus ollama and mock. With no key at all the judge option is disabled, with a link to Settings. Judges run only while Studio is running; until then their jobs wait in the daemon (see Judge rules). Set LOUSHO_STUDIO_JUDGE=0 on the Studio server to turn its judge loop off.
Test on trace on a rule’s page dry-runs it on one trace id (?trace= prefills it) and shows the value and comment; no score is written. The Studio runs a judge rule itself and forwards a code rule to the daemon. An unknown trace shows “Trace not found”.

Annotation queues

Reviewing an item: the trace beside the rubric #/evals/queues lists the queues (pending, done, skipped) and has a New annotation queue form: a name and a rubric, one row per score (name, optional description, optional min and max). Add traces from a trace’s Add to queue (or many at once with the queue API). Open a queue to review it: the next pending item’s trace in the trace viewer, beside one number input (within the rubric’s bounds) and an optional comment per rubric entry. Submit (Enter) saves the filled-in scores as human scores on the trace and moves to the next item; Skip (S) skips it. A blank input is not scored. When nothing is pending the screen says the queue is empty.

Prompts

A prompt: its labels, actions and a diff between two versions #/prompts lists the registry, one row per prompt: latest version, labels, version count, runs that used it, and when it was updated; the search box filters the list by name. Open one (#/prompts/<name>, or @<version> / @<label> to select a version):
  • The header: the prompt’s name with the selected version’s labels, Runs using this version (Traces filtered by prompt=<name>@<version>) and Open in Playground.
  • The selected version’s text, with line numbers, and Move <label> here for each of the prompt’s labels that points elsewhere: a label points at exactly one version, so this moves it (the same as lousho prompt label, see CLI).
  • Compare versions: pick two versions for a diff (?diff=a,b), shown Unified or Side by side.
  • The version history, a timeline beside the text; pick a version to select it (j/k move between versions).

Context Hub

#/hub shows the context hub’s namespaces. The daemon serves hub entries only on behalf of an agent, so pick who you are Viewing as (default the first agent by name) and, optionally, a scope (private or fleet). Open a namespace to see its entries as cards (key, scope, a value preview, writer, last update and TTL); open a card to see the full value (JSON as a tree) beside the list. A fleet entry has an Edit button that republishes it (which restarts its TTL).

Settings

#/settings is one column of cards: Appearance (theme Light, Dark or System, and table density Compact or Comfortable, both remembered in this browser; until you pick a density each table keeps its screen’s default), Provider keys, Settings profile, Deploy target, Collector (whether the observe daemon answers, its address, and lousho observe start when it is down) and Keyboard shortcuts (the same list as the ? sheet). The builder drawer’s Settings tab shows only the provider keys, profile and deploy cards; see Settings, secrets and deploy wiring.

First-agent walkthrough

  1. Create an agent. On the agents list (#/agents) click New agent and pick Blank agent - it starts from an empty canvas, which is the fastest way to try things out without any API keys (From template offers ready-made starting points instead). Agent Forge creates the agent (.lousho/agents/<id>.yaml, with name: in the spec) and opens it on the canvas. The open agent’s card has Rename and Delete. Rename moves the spec to the new name; earlier chats, traces and checkpoints stay under the old one.
  2. Look at the graph. A blank agent is a single agent node. Drag more nodes in from the rail’s Nodes tab (a Tool, an MCP server, a Guardrail, a Chat trigger, an Output schema — the full list is in the visual builder), or click (or press Enter on) a Nodes item to add it at the centre of the canvas, and connect them by dragging between their handles. Each node card shows its name, an agent node’s provider/model chip, and the node’s status in the current run (idle until a run reaches it). Click a node to edit its settings in the Inspector on the right; its Problems, Settings and Debug sections collapse, and each stays the way you left it.
  3. Run it. Click Run in the top bar. With the mock provider there’s nothing to configure - it returns deterministic canned output, which is exactly the point for trying the rest of the UI without needing a real LLM API key. The status pill in the top bar tracks the run (running → done, stopped after you press Stop, error or awaiting approval), and once the run’s trace id is known an Open trace link next to it opens the run at #/traces/<traceId> (in the narrow layout it is in the More menu). Builder runs report to the observe collector as agent <agent id>, the same way the Playground does (see The collector): a collector that is down only drops events and never fails the run, and message content is sent only to a loopback collector (never to the trace files or the live Trace tab). Run sends a fixed prompt, which the Test tab’s chat shows as a Run input bubble instead of a message from you. If the studio server goes away, a banner says the connection was lost and the studio reconnects when it is back.
  4. Watch it in the debug console. Open the bottom drawer’s Logs tab for a live, filterable log feed of the run (trigger/llm/tool/ sandbox/checkpoint/approval events), or Trace for the run’s steps in the same trace viewer the Traces screen uses (a tree or a waterfall, with an inspector for the selected step). Turn on Debug in the top bar (or set a breakpoint on a node in the Inspector) to pause the run at LLM/tool boundaries and step through it with the debug bar’s Step/Continue controls; expand “Live message array” there to inspect the in-flight message list. Output shows the full ExecutionResult (messages, tool calls, usage, steps) as a collapsible JSON tree once the run finishes or pauses. Drag the drawer’s top edge (or focus it and use the arrow keys) to resize it; the height is remembered. Trace history. Every run is also saved as a trace file, so the Trace tab keeps the runs of the agent after the page is reloaded or the server restarted. A list on the left shows the agent’s past runs, newest first (start time, duration, model calls, tokens in/out, cost, status), with a Live entry on top while a run is active; choose one to open its steps in the same viewer: each step’s kind (model call, tool call or span), model, tokens and duration, failed steps in the error colour with the failure message in the inspector, and steps still running ticking live. Selecting a step highlights its node on the canvas. The list refreshes when a run ends. The files are the ones lousho traces reads, in .lousho/agents/<agent id>/traces/<day>/<trace id>.jsonl under the workspace folder (see Local traces): npx lousho traces --dir .lousho/agents/<agent id>/traces shows the same runs in the terminal, and deleting the agent’s folder deletes its traces. The tab shows what the spans hold: model and tool names, token counts, cost, durations and error messages, and in the inspector’s Input, Output and Attributes sections the attributes, which carry prompt and tool content. The server reads traces only from that folder (an id with a path separator is a 400) and never sends the file path to the browser. Keep .lousho/ out of version control.
  5. Chat with it. The chat in the bottom drawer’s Test tab is a separate conversational transport (POST /agents/:id/message, streamed back over the same WebSocket as everything else) - send it a message and it replies in the thread, independent of the graph “Run” button above. Each agent keeps its own chat history (+ New chat starts a fresh session; old ones stay browsable).
  6. Approve a paused tool call. Add a Tool node, open it in the Inspector, and pick a tool - some tools (or an agent’s own policy) can require human approval before running. When a run or chat hits one, an inline approval card appears (in the top bar for a graph run, or as a message bubble in the chat thread) showing the tool name and its arguments. Click Approve to let it proceed or Reject to abort that call; the run resumes automatically either way.

Hooks

Hooks are small, sandboxed functions that run immediately before or after a tool call or a model call - the same mechanism the SDK core exposes as HookRegistry/AgentHook (see API Overview), authored visually as hooks[] entries on the agent. To add one:
  1. Drag a Hook entry from the rail’s Nodes tab (Safety group) onto the canvas, or click it while the agent is open; it attaches to the agent as a node. Each spec hooks entry is one node.
  2. Click the hook node and edit its fields in the Inspector: an id, a name, the Source (Code here for an inline body, or File for a .ts/.js file inside the agent folder), the Runs point - Before/After each tool call or Before/After each model call - the on switch, and the code itself in a CodeMirror editor, with starter templates (redact-pii, rate-limit, audit-log, inject-context) filtered to the current point.
  3. The code is the body of an async function invoked as hook(ctx) inside a sandboxed subprocess (server/hookSandbox.ts) - never in the browser or the API server process itself:
    • For a tool-call point, ctx is { toolName, args, result?, error? }. A pre-hook can mutate ctx.args; a post-hook can inspect/mutate ctx.result/ctx.error. Return ctx.
    • For a model-call point, ctx is { messages, model }. Mutate/push onto ctx.messages and return ctx.
    • Throwing aborts the step - a rate-limit hook, for example, throws to block the tool call outright rather than letting it run.
  4. Switch a hook off without removing it, or delete its node; only enabled hooks are compiled into the run.
Example: a redact-PII pre-hook on a tool node (this is the redact-pii starter template) -
Saving the agent persists these as hooks entries in the agent’s YAML; the server compiles enabled hooks into a real HookRegistry for the run (server/compileHooks.ts), routed through the same SandboxAdapter a sandboxed tool uses.

Time travel

Agent Forge keeps every run’s checkpoints, not just the latest: its file store (server/checkpointStore.ts) keeps the same bounded history as the SDK’s LocalStorageCheckpointStore (the newest 50 saves per run, under .lousho/agents/<id>/checkpoint-history/; see Checkpoint history). From that history you can fork a run at any step, change what happened there, and replay it next to the original, with AgentExecutor.fork() and compareTrajectories() doing the work.

The History tab

  1. Run the agent (Topbar Run, or a chat message).
  2. Open the bottom drawer’s History tab. It lists the run’s steps: step number, status, the model’s finish reason, the tool calls made, and the tokens and cost of the step’s model call when known.
  3. Click Edit and replay from here on a step. Choose Append a user message and type one, or pick one of the step’s tool calls to edit its result (prefilled with the recorded result; text that parses as JSON is sent as JSON).
  4. Click Fork and replay. The run is forked at that step with your edit and started as a new run, <id>.fork-<n>.
  5. The fork opens next to the original as a side-by-side trajectory: each model turn of both runs (text, tool calls and results), the first turn where they differ highlighted as diverged, and the drift entries (tool order, arguments, step count, finish reason) listed below. It refreshes when the fork finishes.

Routes

A run id is the run’s checkpoint session id: the agent id for the agent’s own runs, <id>.fork-<n> for a fork of run <id>. The runtime control server has three routes for it (the History tab uses them), and two more for an agent’s saved traces (the Trace tab uses them): The flow, for an agent weather that has run once:
The fork is a run of its own: the original run’s checkpoints, status and chat are unchanged.

Playground run endpoint

POST /playground/run runs a one-off prompt against a model and streams the reply as server-sent events. It carries the same access token as the rest of the API. The body:
  • messages (required): 1 to 200 { role, content }, role one of system, user, assistant. They are sent as written; the server adds no system prompt of its own.
  • variables: string values. Every {name} in every message’s content is replaced by variables.name; a placeholder with no variable is left as is.
  • model (required): provider/model, or a bare provider (mock). The provider key comes from Settings > Provider keys, then the environment, the same way agent runs resolve it.
  • tools: tool names the Studio resolves for agents (current-date, day-name, http, web-fetch, demo-approval). A tool that needs approval ends the run with finishReason: "awaiting-approval"; the playground has no approval flow.
  • promptRef: the registry prompt the messages came from (name, name@label or name@3). It is only recorded on the trace; the server does not fetch the prompt.
A bad body gets 400 { error }. Otherwise the response is 200 with content-type: text/event-stream, one data: <json> frame per event: Every stream ends with exactly one done or error, even a run that stops without a result. usage has the run.done event’s usage shape (AgentEventUsage). Closing the connection aborts the run. Every run reports to the collector the Studio reads (see The collector) as agent playground, with lousho.prompt.ref on the run’s root span when promptRef is given. A bearer token is sent when one is configured, for a collector bound beyond loopback. A collector that is down does not slow or fail the run.

Settings, secrets and deploy wiring

The Settings screen (#/settings, the last screen in the nav) and the builder drawer’s Settings tab share three parts: provider API keys (OpenAI and Anthropic, stored encrypted under ~/.lousho/studio/ and never shown again; each key shows Set with its masked last characters, From environment when only OPENAI_API_KEY / ANTHROPIC_API_KEY is set, or Not set), named settings profiles (provider, deploy adapter, hook timeout, OpenTelemetry toggle; kept in ~/.lousho/studio/settings.json, which holds no secrets), and a Deploy section that picks an adapter (node-server, docker or cloudflare-worker) and runs lousho build for the selected agent. Other providers still read their environment variables, the same way lousho dev/lousho build do (see Configuration), and the mock provider needs no credentials. Stored keys are encrypted with AES-256-GCM in ~/.lousho/studio/secrets.json. The encryption key is generated on first use and kept next to it in ~/.lousho/studio/secrets.key (both 0600 on POSIX). This keeps keys out of anything that copies the ciphertext alone - a backup, a zip of the project, a shared agent YAML - but anyone who can read both files as your user can decrypt them. It is not an OS keychain. Keep ~/.lousho/studio/ out of version control and out of shared archives, and prefer environment variables on shared machines. An agent whose provider has no key (no stored key and no environment variable) does not run. Run and Chat fail with LOUSHO_PROVIDER_MISSING_API_KEY and a message naming the fix: add the key in Settings, set the environment variable, or switch the agent’s provider to mock. The studio never swaps in the mock provider on its own. The top bar’s provider pill shows the provider/model the agent actually runs on, and a mock agent carries a MOCK badge.

Dev mode

Dev mode exists only for people contributing to Studio inside the SDK’s own monorepo - an installed Studio is always the production bundle (see Production vs. dev mode). From a checkout of this repository, lousho studio detects the Studio source and falls back to dev mode automatically as long as apps/agent-forge/dist-server hasn’t been built yet:
This runs the API server straight from TypeScript (tsx) and a real Vite dev server with hot-module reload for apps/agent-forge/src/**, as two sibling processes. Open the printed http://localhost:5173/?token=... URL; Vite is pinned to port 5173 and the API server accepts that origin. To build the production bundle used by everyone else (and to verify what actually ships):
npm run build:studio also runs automatically as part of the root prepublishOnly script, so a published npm publish can never ship a stale or unbuilt studio.

E2E smoke test

apps/agent-forge/e2e/studio.spec.ts is a headless Playwright test that drives the real, built lousho studio (the same dist-server/index.cjs production server, not a dev-mode Vite server) through a browser: it creates an agent from the “Support bot” template, retargets its tool node at a server-local demo-approval tool (always needsApproval: true - see server/buildAgent.ts’s doc comment for why this exists, since none of the SDK’s spec-resolvable built-in tools require approval), sends it a chat message that triggers the mock provider’s tool-call heuristic, waits for the run to pause on the approval gate, approves it via the Test tab’s inline approval card, and asserts the run completes. Run it with:
This builds Agent Forge first (build:studio), then runs Playwright against it: studio.spec.ts above plus the other specs in apps/agent-forge/e2e/, among them revamp.spec.ts (the revamp’s acceptance checks: a failed run’s error in two interactions, every route surviving a reload with its filters) and a11y.spec.ts (an axe scan of every route in routeTable.ts). The daemon screens run against a fake daemon (e2e/observeStub.ts and e2e/fixtures/seedObserve.ts), so no lousho observe is needed.

Docs screenshots

The screenshots in this doc come from apps/agent-forge/e2e/docShots.spec.ts, which is skipped unless LOUSHO_DOC_SHOTS is set. After npm run build:studio, regenerate them from the repo root with:
It writes docs/images/studio-<screen>.png (1280x800, light theme) from the same fake daemon. The images are not part of the npm package. The dark examples (studio-{agents,traces,trace,monitoring}-dark.png) come from the same command with the dark scheme:
Into docs/images the spec skips its x- review shots, and a dark run writes only those four. Two optional variables help review a restyle before and after: LOUSHO_DOC_SHOTS_OUT=<dir> writes the PNGs to another directory (absolute, or relative to where you run the command), and LOUSHO_DOC_SHOTS_SCHEME=dark shoots the dark theme (light is the default; any other value fails the run). With an output directory every shot is written under its own name, x- review shots included.