Inspector

Source: docs/inspector.mdx Canonical URL: https://sandboxagent.dev/docs/inspector Description: Debug and inspect agent sessions with the Inspector UI.

The Inspector is a web UI for inspecting Sandbox Agent sessions. Use it to view events, inspect payloads, and troubleshoot behavior.

Open the Inspector

The Inspector is served at /ui/ on your Sandbox Agent server. For example, if your server runs at http://localhost:2468, open http://localhost:2468/ui/.

You can also generate a pre-filled Inspector URL from the SDK:

import { buildInspectorUrl } from "sandbox-agent";

const url = buildInspectorUrl({
  baseUrl: "http://127.0.0.1:2468",
});

console.log(url);
// http://127.0.0.1:2468/ui/

Features

Session list
Event stream view
Event JSON inspector
Prompt testing
Request/response debugging
Interactive permission prompts (approve, always-allow, or reject tool-use requests)
Desktop panel for status, remediation, start/stop, and screenshot refresh
Process management (create, stop, kill, delete, view logs)
Interactive PTY terminal for tty processes
One-shot command execution

When to use

Development: validate session behavior quickly
Debugging: inspect raw event payloads
Integration work: compare UI behavior with SDK/API calls

Process terminal

The Inspector includes an embedded Ghostty-based terminal for interactive tty processes. The UI uses the SDK's high-level connectProcessTerminal(...) wrapper via the shared @sandbox-agent/react ProcessTerminal component.

Desktop panel

The Desktop panel shows the current desktop runtime state, missing dependencies, the suggested install command, last error details, process/log paths, and the latest captured screenshot.

Use it to:

Check whether desktop dependencies are installed
Start or stop the managed desktop runtime
Refresh desktop status
Capture a fresh screenshot on demand

2.0 KiB Raw Permalink Blame History