> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Operate governed computer-use agents from the console > Set a computer-use tool’s guardrails, prove them with a dry-run, then observe every session and replay the per-step audit trail from the Computer use tab on the agent page. # Operate governed computer-use agents from the console A computer-use tool lets an agent drive a real web UI one guarded browser action at a time: navigate, click, type, screenshot. The [API reference](https://docs.orbit.devotel.io/agents/computer-use.md) covers the endpoints; this guide covers the operating loop around them: decide the guardrails, prove them with a dry-run before going live, then observe and audit every run from the **Computer use** tab on the agent page in the Devotel Orbit console. The tab is the observe-and-audit surface for computer use. It lists every session the agent has driven, filters the list by outcome, and replays the ordered action trace of the session you select. Launching and steering a session is owned by the agent runtime; the console reads what happened, it does not drive the browser. ## 1. Configure a computer-use tool Creating, updating, and deleting tools goes through the API today (`POST /api/v1/agents/{agentId}/computer-use-tools`); the console tab is where the tool's runs are observed. Full request bodies live in the [API reference](https://docs.orbit.devotel.io/agents/computer-use.md#2.-create-a-computer-use-tool). Four knobs are worth deciding deliberately, because they define what you will later audit in the tab: | Field | What it controls | What you see in the tab | | - | - | - | | `allowed_domains` | The only hosts `navigate` may reach; subdomains of a listed domain are allowed. | Off-list navigation attempts show as denied steps in the trace. | | `max_steps` | The loop budget, 1–50 steps (default 20). A run that exhausts it is forced to stop. | The Steps stat, and a trace that ends where the budget ran out. | | `require_confirmation` | Action kinds that pause at `require_confirmation` until an operator sends an explicit `confirmed` flag. | Gated steps wait instead of dispatching; the run reads as still in flight until confirmed. | | `blocked_actions` | Action kinds the agent may never perform. | A blocked proposal shows as a denied step, never as a sandbox dispatch. | The `sandbox_url` and `sandbox_secret` fields point the tool at your own sandbox executor and are validated at write time; the console never shows the secret, only that one is set. ## 2. Validate guardrails with a dry-run before going live Before you let an agent run the tool live, dry-run one representative proposed action per behavior you care about: one `navigate` per allowed domain, one action kind you put on `require_confirmation`, and one you put on `blocked_actions`. `POST /api/v1/agents/{agentId}/computer-use-tools/{toolId}/dry-run` with `{"dispatch": false}` returns the guardrail verdict without touching the sandbox; `{"dispatch": true}` (the default) also forwards the action once, marked as a test. The reference's [dry-run section](https://docs.orbit.devotel.io/agents/computer-use.md#3.-validate-guardrails-with-a-dry-run) has the full request and response shapes. Read `decision` on each dry-run and expect the verdicts you configured: `allow` for the in-list navigation, `require_confirmation` for the gated kind, `deny` with `ACTION_BLOCKED` for the blocked kind. Dry-runs never consume a step budget and are safe to run in CI. The console equivalent starts where the dry-run ends: the tab has no dry-run control of its own, because it renders live runs. Once the tool is enabled, watch the first real session in the tab and check that each step's outcome matches what the dry-runs predicted. A mismatch between the dry-run verdict and the live trace means the tool configuration changed in between; re-read the tool over the API and diff the four knobs above. ## 3. Observe sessions in the Computer use tab Open the agent page and select the **Computer use** tab. A filter row sits above the session list: All / Active / Completed / Failed. The filters map one-to-one onto the `?status=` parameter of `GET /api/v1/agents/{agentId}/computer-use/sessions` (`active` covers runs still in flight), so what you filter in the tab you can also pull over the API. Each row in the list is one session and shows: * **Goal** — the task the agent was working, as supplied at launch. * **Status** — Running or Needs input while in flight; Completed, Failed, or Cancelled once terminal. * **Steps** — how many browser actions the run took, and **errors** — how many of them failed, shown only when nonzero. * **Duration** — first step to last step; for a running session the value ticks up live. Select a row to open the detail panel: Steps, Errors, Duration, and Model stats, the start time rendered in your timezone, the last URL the browser landed on, the run's result summary when the agent wrote one, and the ordered action trace below. ## 4. Replay the per-step audit trail The trace is the run reconstructed step by step. Each row carries the step number, the action kind (Navigate, Click, Type, Key, Scroll, Screenshot, Extract, Wait, Finish), a success or failure marker, the action's description and target (a URL for Navigate), and, when the step failed, the error string returned by the sandbox. Steps that captured a screenshot link it inline, so you can see the page exactly as the agent saw it. The trace in the tab is the same record `GET /api/v1/agents/{agentId}/computer-use/sessions/{sessionId}` returns: each step's action, guardrail decision, sandbox status, and duration. What you can read in the tab you can export over the API into your own audit pipeline, and the per-step records survive restarts, so a run is always reconstructable after the fact. ## 5. When to require human confirmation, and what read-only means Put an action kind on `require_confirmation` when the action is hard to reverse or leaves the scope you can fully audit: submitting a form, confirming a payment, deleting a record. The guardrail then answers `require_confirmation` for that kind and the step waits for an explicit `confirmed` flag before it dispatches; nothing happens on the operator's silence. Keep the list short. Every gated kind is a step that cannot complete unattended, so gate the kinds that are genuinely consequential and let the rest run inside the domain and step-budget containment. Read-only here means the console never launches, steers, or stops a session; that is the agent runtime's job. The tab observes and audits. The controls that govern a run — allowed domains, blocked actions, confirmation gates, step budget — are yours, set per tool on the agent; the platform enforces them structurally on every step, capped loop, re-pinned sandbox URL, and a written audit record whether the step was allowed, denied, or gated. ## 6. Failure triage Start with the **Failed** filter. Open the session and read top down: the Errors stat, the "{n} of {m} steps failed" note above the trace, then the failed rows, each carrying its sandbox error string. Two failure shapes are worth distinguishing: * **Sandbox failures** — the guardrail allowed the step and the sandbox rejected or errored it. The row shows the error; retrying means fixing your executor, not the tool configuration. * **Guardrail denies** — the step never reached the sandbox. The trace shows the deny (`ACTION_BLOCKED`, `DOMAIN_NOT_ALLOWED`, `STEP_BUDGET_EXHAUSTED`); these surface in the trace, not as HTTP errors. They mean the configuration did its job, or that the agent's goal needs domains or actions you have not allowed. Configuration-time failures are a third shape: a create or update whose `sandbox_url` misses safety validation returns a 422 `INVALID_SANDBOX_URL` envelope that names the reason. See [Failure envelopes](https://docs.orbit.devotel.io/agents/computer-use.md#failure-envelopes) in the API reference for the body, and [Troubleshooting agent errors](https://docs.orbit.devotel.io/troubleshooting/agent-errors.md) for the wider agent failure classes — budget caps, provider errors, run-level faults. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.