# Studio (/docs/run/studio)



`nylorun start` prints Studio's URL, `http://localhost:4161` by default. Open
it in a browser on the same machine: Studio needs no login on its loopback
address. To open it from the terminal:

```sh
npx nylorun studio
```

Behind a sign-in proxy, or embedded in another app, Studio keeps that
sign-in.

Studio is the dashboard for this Tenant only, and each Tenant has its own
port. It opens on the **Agents** list. A Tenant with no Agents yet shows its
name, id, and the Runtime's status; the Agents appear when the first is made.

## Sidebar [#sidebar]

| Item                   | Opens                                                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| The Tenant, at the top | [The Tenant](#the-tenant) page, beside the Runtime's status.                                                             |
| **Agents**             | The [Agents list](#agents-list).                                                                                         |
| Each Agent under it    | Its [Agent page](#agent-page). A dot shows its state, and a count shows only when its sessions wait on a person or fail. |

Hovering an Agent shows **+**, which opens a new session on it as
`local-developer`. An Agent whose owner guard names another owner offers none.

Sessions, manifests, models, and artifacts have no sidebar item: each opens
from the Agent or the Tenant it belongs to. Links to `/sessions`,
`/agent-manifests`, `/settings`, and `/artifacts` still open their place.

## Agents list [#agents-list]

The **Agents** list (`/agents`) has one row per
[Agent](/docs/run/agents): its id and labels, the manifest version it runs
(`triage@3`, tracking the manifest or pinned), its state (the reasons in a
tooltip), its kind, its sessions and how many wait on a person, and its last
activity. Agents that need input come first, then failing ones, then the rest
by last activity. Search by id or manifest, and filter by state, manifest,
owner, or label; selecting a manifest or a label in the table filters on it.
Each row's ⋯ opens the Agent, opens a **New session** on it, or copies its id.

**New Agent** makes one from a saved manifest: the manifest, **Track the
latest** or a version to pin, its id, its owner guard (`local-developer`, the
owner of Studio's sessions, by default), and labels. Making an Agent opens no
session.

## Agent page [#agent-page]

An Agent's page (`/agents/<id>`) is a dashboard of the manifest version it
runs. Its header names that version (linked to it), whether it tracks the
manifest or is pinned, its kind, its owner guard, and its labels, with **New
session** and a ⋯ menu:

| Action                    | Does                                                                                                                                                                                                                    |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Edit labels and owner** | Change its labels and owner guard.                                                                                                                                                                                      |
| **Stop compute**          | For a pod: stop its sandbox.                                                                                                                                                                                            |
| **Reset disk**            | For a pod: start it again on a new, empty volume.                                                                                                                                                                       |
| **Fork into a new Agent** | Make a new Agent from a manifest version, with a disk that starts as a snapshot, a disk version, or empty, and the secrets the new version declares. **Check** shows the plan first. See [Fork](/docs/run/agents#fork). |
| **Delete Agent**          | Delete it, its secrets, its disk, its disk versions, and its memories.                                                                                                                                                  |

Reset and Delete say how many sessions run on the Agent before they act.

Each tab is a table with a search, filters, and a count. A row's actions are
behind its ⋯, and a row opens its details in a panel on the right. The page
opens on **Sessions**:

| Tab           | Shows                                                                                                                                                                                                                                                                                                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sessions**  | The sessions on it, by last activity, filtered by who started them and their status. A row opens the [session](#session).                                                                                                                                                                                                                                              |
| **Triggers**  | Its [triggers](/docs/run/triggers): each one's schedule in words, the session its runs go to, its next run, and its status, with **Run now**, **Pause**, **Resume**, and **Copy webhook URL**. Below, every run, newest first.                                                                                                                                         |
| **Artifacts** | What its sessions made, and the input files its runtime copies in. A row opens the artifact.                                                                                                                                                                                                                                                                           |
| **Memory**    | Its [memory](/docs/run/memory): each memory with its description, version, and who changed it last. A row opens its content and history; **Delete** removes it.                                                                                                                                                                                                        |
| **Disk**      | Its [disk versions](/docs/run/agents#disk-versions), newest first: **Snapshot now** keeps one, and a row's **Restore**, **Fork into a new Agent**, **Delete**, and **Browse** (its files and changes). Not shown for kind `none`.                                                                                                                                      |
| **Activity**  | Its events, newest first: its lifecycle and the connections its sandbox opened, filtered by type and result.                                                                                                                                                                                                                                                           |
| **Vault**     | Its [secrets](/docs/run/credentials): each slot its manifest version declares, with its type, what uses it, and whether it has a value. **Set value** asks only for the value; the slot gives the rest. Values are never shown. A secret no slot declares can only be deleted.                                                                                         |
| **Manifest**  | The version it runs as a readable spec: the harness section (instructions, tools, skills, MCP servers, memory), then the runtime section (compute, lifecycle, network, setup and input files, secret slots, triggers, limits). Each HTTP tool and MCP server notes the [tool policy](/docs/run/tool-policy) rules on it. A row opens its part of the manifest as JSON. |

The **Manifest** tab's ⋯ moves the Agent within its manifest (see
[Versions](/docs/run/agents#versions)), shows the whole manifest, or opens all
its versions:

| Action                           | Does                                                               |
| -------------------------------- | ------------------------------------------------------------------ |
| **Pin** / **Track the manifest** | Keep it on the version it runs, or follow every version saved.     |
| **Move to vN**                   | For a pinned Agent, move it to another version.                    |
| **Restart**                      | For a pod that waits to start on a new version: apply it now.      |
| **Retry**                        | For a pod whose start on a version failed: try that version again. |

Links to the tabs an Agent page had before still open their place:
`?tab=overview` opens Sessions, `secrets` Vault, `setup` Manifest, and
`events` Activity.

Studio is one more client: any credential that may write Agents does the same
with the CLI or the SDK.

## The Tenant [#the-tenant]

Selecting the Tenant at the top of the sidebar opens its page (`/tenant`). Its
header names the Tenant, its id, the model it runs, its sandbox, and how many
Agents and sessions it holds. Its ⋯ copies the id and resets the Tenant:
**Reset sessions…**, **Reset Agents…**, or **Reset everything…**, each after a
confirm, as `nylorun tenant reset` does (see
[Reset a Tenant](/docs/run/tenants#reset-a-tenant)).

The tabs follow in the order an Agent's turn meets them. The page opens on
**Status**:

| Tab             | Shows                                                                                                                                                                                                                                                                                                                                                                             |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status**      | The Tenant's checks (store, scheduler, model, schema), what runs it (harness, sandbox, event streams), and what it holds, each row linked to the tab that configures it.                                                                                                                                                                                                          |
| **Manifests**   | Its [agent manifests](#manifests).                                                                                                                                                                                                                                                                                                                                                |
| **Models**      | The providers it has a credential for, the one it runs, and what each model reads. See [Models](/docs/run/models).                                                                                                                                                                                                                                                                |
| **Compute**     | The sandbox the Runtime chose and the backends it found, the most an Agent's runtime section may ask for, where harnesses may run, and what artifacts and skills may hold. **Edit compute settings…** saves only what it changes.                                                                                                                                                 |
| **Tool policy** | The [tool policy](/docs/run/tool-policy)'s rules, strictest first. A row opens one to edit; **Add rule** adds one. The policy is saved whole.                                                                                                                                                                                                                                     |
| **Limits**      | The [Runtime limits](/docs/run/limits) by area, each beside its default, with a changed one in bold, including an **Agent folders** group. A row opens one to edit in its unit; **Reset to default** drops it.                                                                                                                                                                    |
| **Usage**       | What model calls used today, this month, and in all, and the [budgets](/docs/run/models#usage-and-budgets) with what each period used. A row edits a budget; **Add budget** adds one.                                                                                                                                                                                             |
| **Traffic**     | How the Runtime is running, read live from the runtime's and the gateway's `/metrics` every 10 seconds: API requests by route and client, model calls and tokens, MCP tool calls, turns, queue waits, egress, and dropped telemetry, with counts since each process started, the current rate, and p50 and p95. Nothing is stored. See [Monitor](/docs/deploy/monitor#in-studio). |
| **Keys**        | The application keys and signing keys, read-only: make, rotate, and revoke them with `nylorun tenant keys` and `nylorun tenant signing-keys`.                                                                                                                                                                                                                                     |
| **Audit**       | The Tenant's audit, newest first: keys, signing keys, tool policy and settings changes, Agents' secrets written and used, and Studio sign-ins, each with who acted. A type filter and **Load more**. See [Monitor, Audit](/docs/deploy/monitor#audit).                                                                                                                            |

### Manifests [#manifests]

The **Manifests** tab lists the Tenant's
[agent manifests](/docs/run/agent-manifests): each name with its description,
its latest version, the kind of Agent it makes (`flow · …` for a flow), how
many Agents were made from it, and when it was saved. A version saved from an
[agent manifest](/docs/build/agent-manifests) is marked beside its number. Search
by name or description, and filter by kind, type (Agent or flow), and whether
any Agent was made from it.

A row opens the manifest beside the list, with a version picker, its
description, the Agents made from it (each with the version it runs), and two
views of the version:

| View       | Shows                                                                                                                                                                                                                                                                                                                                                              |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Spec**   | The version as a readable spec, its **Harness** section, then its **Runtime** section, one line each. A line opens its part of the manifest as JSON.                                                                                                                                                                                                               |
| **Source** | The files the version was saved from, read-only: its files as a tree, each marked when it was added or changed since the version before, with the removed ones last. A file opens beside it as text, or as its size when it is not text. A version saved as JSON has no source, and says so. See [Compare versions](/docs/build/agent-manifests#compare-versions). |

The manifest's ⋯ makes an Agent pinned to the version shown (**New Agent from
vN**), shows the whole manifest as JSON, or copies its name.

Manifests are not edited in Studio: edit an agent's folder in its repository,
and save its next version with
[`npx nylorun apply`](/docs/run/agent-manifests#cli) or **Upload folder…** on
the tab's toolbar. **Upload folder…** picks a directory in the browser,
leaving out `.git`, `.hg`, `.svn`, and `node_modules` as `nylorun apply` does,
uploads the files the Runtime does not hold yet, and shows the plan of the
save: what it would change, its errors and warnings, and the compiler's
diagnostics by file, line, and column. **Save vN** saves it, refused
if another save came in between, and opens its Source view. The manifest takes
the name `AGENT.md`'s frontmatter gives it, or else the directory's.

## Session [#session]

A session's page is `/agents/<agentId>/sessions/<sessionId>`. Its header shows
its Agent, the session's short id (click to copy), its status, and a button
that hides the inspector, which the browser remembers. The chat opens at the
newest message. Assistant replies render as Markdown (tables, lists, and code;
raw HTML stays text), and a message shows its time on hover.

The message card holds the text and one button, with the model picker under
it. **Enter** sends and **Shift+Enter** adds a line. While a turn runs, the box
stays focused but read-only, and the button stops the turn, as
`session.cancel()` does. To attach files, use the paperclip, or paste or drop
them onto the card. Any file goes: each shows as a chip until the message is
sent, and Studio uploads each into the session and sends the message as text
and file parts. See [Files](/docs/run/files).

The inspector has four tabs, the same for an agent and a flow:

| Tab          | Shows                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Manifest** | What the agent is. **Declared**: the manifest the session runs, named `name@version`, with its instructions, tools, skills, and MCP servers, each skill and server with its plugin's badge; it says when the manifest has a newer version. **Deployed**: where it runs: its Agent (linked to its page), kind, state, and compute, the version the session opened on beside the one the Agent runs, the harness, sandbox, and allowed hosts, what its MCP servers and HTTP tools get from the Agent's secrets ([coverage](/docs/run/credentials#coverage)), its latest disk version, the connections its sandbox opened during this session's turns, and the other sessions on it. Read-only: change the Agent on its own page. |
| **Record**   | The session's artifacts: its outputs and the files sent into it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **Events**   | **Log**: history and live events, the same stream `session.observe()` reads, in three views: **Agent** (what the agent saw and did, the default), **Runtime** (what the Runtime did to the session), and **All**; each row shows its writer and evidence. **Trace**: a turn's [trace](/docs/run/traces) as a waterfall, the turn, each model call with its model and tokens, and each tool call; select a span for its attributes, and **Open event** for the log event it came from. An event's details offer **Open trace**. A flow adds **Progress** (its stages, live) and **Iterations**, and opens on Progress.                                                                                                          |
| **Usage**    | What the session cost. A **Session** card with one tokens bar and a ledger of tokens and cost by kind (cached input, uncached input, cache writes, output) adding up to a total; then the model calls by turn, each with cached, uncached, output, and total tokens, time, and cost. A call's **View event** opens its event in the Events tab. See [usage by token kind](/docs/run/models#a-sessions-usage-by-token-kind).                                                                                                                                                                                                                                                                                                    |

Links to the tabs a session had before still open their place:
`?inspector=agent` opens Deployed, `artifacts` opens Record, and `tree` and
`iterations` open the Events tab's flow views.

Each tool call, in the chat and in the event details, shows its kind, its
server or skill, and its plugin's badge. An MCP tool shows as `server / tool`,
with the name the model called it by when that differs, such as
`github / create_issue (as github__create_issue)`. A tool call whose result was
stored as an artifact links to it.

A turn paused by the [tool policy](/docs/run/tool-policy) shows an approval
card for each held call, with its tool by the same name, why it is held, and
its input. **Approve** sends that exact call; **Deny** fails it to the model as
`tool.denied`.

Turns that [triggers and wakes](/docs/run/triggers) start show as ordinary
sessions of the Agent.

## Artifacts [#artifacts]

An artifact opens from where it belongs: a session's **Record** tab, or an
Agent's **Artifacts** or **Disk** tab. The inspector shows a numbered version
with its owner, its history, a preview, and the changes between versions, and
downloads it. `/artifacts` lists every artifact the Tenant holds, newest
first, filtered by kind, session, and labels.

## Security [#security]

Studio is for operators on this machine.

* It listens on loopback only (`127.0.0.1:4161` by default).
* No application or provider key reaches the browser.
* Reach it on another machine through an SSH tunnel. Do not publish the port.

## Telemetry [#telemetry]

Studio sends Google Analytics page views by default. It is off in CI. Turn it
off with any of:

```sh
npx nylorun local telemetry disable
```

`NYLORUN_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1` also disable it.

## Next step [#next-step]

<Cards>
  <Card title="Your project" description="See the generated files and where state lives." href="/docs/project" />

  <Card title="Build" description="Change the agent and add tools." href="/docs/build" />
</Cards>
