---
title: 'Governance'
description: 'Monitor, manage and govern your agents and workflows from Studio: one dashboard for the box on your laptop and the one in your cloud.'
position: 15
---

# Governance

> **Stackbone Studio** is where you govern agents and workflows from the first
> local run to production. Point it at a **box** (the container running your
> workspace, on your laptop under `stackbone dev` or deployed in your cloud) and
> from one browser tab you chat with what you built, follow every run, decide
> what waits for a person, set the rules the runtime enforces, and measure
> whether a change made things better. Nothing you change here needs a rebuild
> or a restart.

![The Studio Overview screen: the workspace name, a banner counting three approvals waiting for a decision, cards for agents, workflows, RAG and approvals, and the last runs.](/images/governance/studio-overview.png)
_The Overview: what the box serves, what waits for a person, and what ran last._

## Govern the agent lifecycle

Build, test, debug, improve and operate against a local or a deployed box.

| Stage   | Where you work in Studio                                                                                                                                                                                                                                                                                  |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Build   | **Catalog** lists every agent and workflow the box serves, read live, with its model, tools and input schema. Open an entry to see which guardrails govern it and which triggers start it. **Prompts**, **Dynamic config** and **Model provider** hold the parts you change without a redeploy.           |
| Test    | **Playground** chats with an agent, or starts a workflow from a typed form, and streams the reply. Any run can become a test case in one click.                                                                                                                                                           |
| Debug   | **Sessions**, **Runs** and **Logs**: open a run and read its trace step by step, with the input and output of each tool call and each workflow step, the tokens it spent and how long it took.                                                                                                            |
| Improve | **Evals** score an agent or a workflow against saved cases, in Studio or from CI. **DB Explorer**, **Storage** and **RAG** show the state the box holds.                                                                                                                                                  |
| Operate | **HITL Inbox** decides what paused for a person. **Guardrails** block, mask or hold a turn. **Recurring jobs** shows what runs on a timer, with its next run and how the last one went. **Connections** and **Triggers** wire outside services in. **Secrets** keeps the keys your code reads at runtime. |

## Follow every run

Every chat turn and every workflow run is a **run**: a row with a status, a
trigger (chat, workflow, cron, webhook, event, job, eval), a duration and a
token count. Open one and the trace shows what happened behind the answer.

![A run's trace in Studio: the run id, status and token count in the header, the add_numbers tool call in the waterfall, and the inspector showing the call's input and output as JSON.](/images/governance/run-trace.png)
_One chat turn: the tool the model called, what it was called with, and what came back._

The waterfall lists the tool calls of a chat turn, or the steps of a workflow
run, in order and with timing. Click one and the inspector prints its input and
output. A run that paused for a person shows the pending decision at the top.
When a guardrail stops a run, the run's output names the rule and the reason.

From the same screen you can:

- **Save as test case**: keep the run's exact input on a case list, turning a
  bad answer into a check that it does not come back. See
  [Measure before you ship](#measure-before-you-ship).
- **Copy run details**: the run and its trace as JSON, for a ticket, a message
  or a coding agent.
- **View run logs**: the `console.*` lines your tools and steps printed,
  filtered to this run.

**Sessions** groups chat turns into conversations, so a multi-turn exchange
reads as one thread with a token total, and each turn drills down to its run.
From a terminal,
[`stackbone runs list`](/docs/cli/reference/runs#stackbone-runs-list) and
[`stackbone logs tail --run <id>`](/docs/sdk/platform/observability#inspecting-runs-from-the-shell)
read the same data.

## Keep a person in the loop

Three things park a run until a person decides, and all three land in the same
**HITL Inbox**:

| What paused                                                             | Where it comes from                                                                                                         |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| A workflow that called [`requestApproval()`](/docs/sdk/humans/approval) | Your code, at the step that must not run without a sign-off: a refund, a payout, a destructive change.                      |
| An agent tool marked with `interruptOn`                                 | Your agent, for a tool that acts on the outside world. [Browser tools](/docs/sdk/agents/browser-tools) show one.            |
| A message a guardrail held with **Ask for approval**                    | The operator's rules, with no code involved. See [Set the rules the runtime enforces](#set-the-rules-the-runtime-enforces). |

![The HITL Inbox listing three pending approvals: one held by the "Wire transfers need sign-off" guardrail and two from the refund workflow, each with its run id, age, timeout and a Decide button.](/images/governance/hitl-inbox.png)
_A guardrail hold and two workflow approvals, waiting in the same inbox._

Open one to decide it. The detail shows the payload the code attached, the run
context around the pause, and the audit log of earlier decisions. Leave a
comment, then **Approve** or **Reject**: the parked run resumes at once, and its
trace records the outcome.

![An approval's detail: the refund payload with amount and orderId, the run context showing the paused hook, an empty audit log, a comment field, and the Reject and Approve buttons.](/images/governance/approval-detail.png)
_What the reviewer sees before deciding._

An approval carries a timeout and a fallback, both set by the code that asked.
When nobody decides in time, the runtime applies the fallback and the run
carries on. The audit log keeps every decision with its comment and time and,
on a deployed box, who made it. New entries arrive live, so the inbox needs no
reload. From a terminal,
[`stackbone hitl approve <id>`](/docs/cli/reference/hitl#stackbone-hitl-approve)
does the same.

## Set the rules the runtime enforces

A **guardrail** is a rule you write once in Studio and the runtime applies on
every chat turn and every workflow run, before your code sees the message. Pick
a check from the catalog (blocked words, a length cap, personal data, prompt
injection, off-limits subjects, harmful content), what it inspects (the
incoming message or the agent's reply), and what happens when it fires: **block
the turn**, **mask and carry on**, or **ask for approval**. Attach it to the
whole workspace, to one agent or to one workflow.

![The Guardrails screen listing three rules: block internal codenames on the incoming message, mask personal data in the agent reply, and hold wire-transfer requests for approval on one agent.](/images/governance/guardrails.png)
_Three rules with an action each. The third one applies to a single agent._

A change applies on the box's next turn, with no rebuild. The
[Guardrails](/docs/sdk/humans/guardrails) page covers the catalog, the actions
and where each rule runs.

Two more things an operator tunes from Studio without touching the code:

- **Prompts** carry versions. Every save adds one, the agent reads the live
  version through [`stackbone.prompts`](/docs/sdk/platform/prompts), and you can
  restore any older one.
- **Dynamic config** is one JSON document per workspace that your code reads
  through [`stackbone.config`](/docs/sdk/platform/config). It keeps a version
  history too, and renders as a form when the workspace declares a
  `config.schema.ts`.

## Measure before you ship

**Evals** turn a case list into a number you can compare across changes. Save
cases from real runs or by hand, build a suite (which agent or workflow, which
case list, which criteria, how many repeats, what pass mark), and run it from
the **Runs** screen under Evals or from CI with
[`stackbone eval <suite>`](/docs/cli/reference/eval),
which exits non-zero below the pass mark. The
[Evaluation](/docs/home/features/evaluation) page walks through the three
screens and the criteria catalog.

## Connect your boxes

Studio governs one box at a time. Pick it from the switcher in the header, and
every screen answers from that box.

| Box                             | How Studio reaches it                                                                                                                                                                                   |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A local `stackbone dev` session | The CLI opens a tunnel and prints an **Open Studio** link. The session shows up under your organization, marked `local`, while it runs.                                                                 |
| A container in your cloud       | You register its address and signing secret once, [from the browser](/docs/home/deployments/connect-your-box) or with [`stackbone link`](/docs/cli/reference/link). Studio calls that address directly. |

The control plane at `app.stackbone.ai` holds the organization, its members
and roles, and the record of where each box lives. It does not hold your runs,
your data or your secrets: those stay in the box, in its own Postgres and object
store. Your browser talks to the box with a short-lived token the control plane
mints for your session, so a box that only answers inside your network still
works from a machine that can reach it.

| Layer          | Role                                                                                                                                                |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Studio         | The browser interface. It reads and writes the box you selected.                                                                                    |
| Control plane  | Organizations, members, roles, and the deployment record for each box. Mints the token your browser presents to the box.                            |
| Box            | Runs your agents and workflows, serves their APIs, enforces guardrails and roles, and keeps runs, sessions, approvals, prompts, config and secrets. |
| Model provider | The OpenAI-compatible endpoint the box calls for models. Your own account, your own bill.                                                           |
| Connectors     | Outside services such as Gmail, Slack or GitHub, reached through Stackbone Connect. The broker inside the box holds their credentials.              |

## Read more

- [Human-in-the-loop](/docs/sdk/humans/approval): `requestApproval()`,
  timeouts, fallbacks and the deciding commands.
- [Guardrails](/docs/sdk/humans/guardrails): the catalog, the actions and where
  a rule runs.
- [Observability](/docs/sdk/platform/observability): logging from tools and
  steps, and the run timeline.
- [Evaluation](/docs/home/features/evaluation) and
  [`stackbone eval`](/docs/cli/reference/eval).
- [Connect your box](/docs/home/deployments/connect-your-box): register a
  deployed container from the browser.
- [Where do agents actually run?](/docs/faqs/general/where-agents-run)