Sandbox Agent

The Inspector provides several tools for interacting with agent sessions:

• Session Management: View a list of active sessions and manage processes (create, stop, kill, delete, and view logs).
• Event Inspection: View the event stream and inspect raw JSON payloads for requests and responses.
• Interactive Controls: Approve, always-allow, or reject tool-use requests via interactive permission prompts.
• Terminal Access: Use an embedded Ghostty-based terminal for interactive TTY processes.
• Desktop Management: Use the Desktop panel to check dependencies, start/stop the desktop runtime, refresh status, and capture screenshots.
• Testing: Perform prompt testing and one-shot command execution.

To optimize performance, WorkbenchTask is split into two distinct interfaces located in packages/shared/src/workbench.ts:

WorkbenchTaskSummary

Used for sidebar-level data. This is materialized in the organization actor's SQLite database to allow for fast, single-query initial fetches of the entire workspace.

• id, repoId, title, status, repoName, updatedAtMs, branch, pullRequest, sessionsSummary.

WorkbenchTaskDetail

Used for full task views. This contains heavy data like file trees and diffs and is only fetched or broadcasted when a user is actively viewing a specific task.

• Includes all summary fields plus: fileChanges, diffs, fileTree, minutesUsed, sandboxes, and activeSandboxId.

The VCS integration provides the following capabilities for managing repository state within a session:

• Repo discovery: Automatically identifies the repository from the session directory with safe fallback mechanisms.
• Status summary: Provides information on the current branch, dirty files, and whether the local branch is ahead or behind the remote.
• Diff generation: Supports generating diffs for staged/unstaged changes, both per-file and for the full repository.
• Revert/unrevert mechanics: Implements state management using temporary snapshots or stashes to allow users to undo or redo changes.
• File status integration: Integrates with existing file status endpoints when available.

sandbox-agent sends an anonymous telemetry payload on startup and every 5 minutes to assist with usage analysis and reliability improvements.

Collected data includes:

• Sandbox Agent version.
• OS name, architecture, and OS family.
• Detected sandbox provider (e.g., Docker, E2B, Vercel Sandboxes).

To maintain anonymity, each sandbox is assigned a random anonymous ID stored on disk. The last successful send time is also stored locally to ensure heartbeats are rate-limited to at most one every 5 minutes.

When you call SandboxAgent.start(), the following sequence occurs:

1. Provision: The provider creates the sandbox (e.g., starts a container or creates a VM).
2. Install: The Sandbox Agent binary is installed inside the sandbox.
3. Boot: The server starts listening on an HTTP port.
4. Health check: The SDK polls the /v1/health endpoint.
5. Ready: Once the health check passes, the SDK returns a connected client.

Note: For the local provider, provisioning is a no-op and the server runs as a local subprocess.

When configuring agents via sandbox-agent, be aware that Claude and Codex handle instruction priority differently. This affects how appendSystemPrompt and projectInstructions interact.

• Claude: The system prompt additions (via --append-system-prompt) have the highest priority, followed by the base prompt, and finally the CLAUDE.md file.
• Codex: The AGENTS.md project file has the highest priority, followed by developer_instructions, and finally the base prompt.

Implication: In Claude, system prompt additions override project files. In Codex, project files override system prompt additions. It is recommended to use only one mechanism to avoid unexpected behavior.

The Sandbox Agent filesystem API uses the following rules for path resolution:

• Absolute paths: Used as-is.
• Relative paths: Resolve from the server process working directory.
• Security: Any requests attempting to escape the allowed root directories are rejected by the server.

The sandbox-agent design distinguishes between interactive terminal sessions (PTY) and request-response execution (Commands) to optimize for latency and complexity:

• PTY (Pseudo-Terminal): Use WebSockets for bidirectional, low-latency, and long-lived interactive I/O (e.g., for terminal emulators like xterm.js). PTYs are treated as unified streams where stdout and stderr are merged by the kernel.
• Commands: Use REST for request-response operations (e.g., running ls -la). Commands are suitable for non-interactive execution where the client sends a command and receives a structured JSON response containing stdout, stderr, and an exit_code.
• Streaming Output: For long-running commands that require streaming output but not interactive input, use SSE (Server-Sent Events). If interaction (like ctrl+c) is required, the user should switch to a PTY.