Sandbox

The machine an agent works in: status, CPU and memory, open ports with links, a logs drawer and a files shortcut.

Markdown

On this page

A sandbox boots, opens its ports and streams logs.

Installation

$ pnpm dlx shadcn@latest add https://chatcn.dev/r/sandbox.json

Usage

tsx

import { Sandbox } from "@/components/ui/chatcn/sandbox"

<Sandbox
  name="sb-7f3a2c"
  status="ready"
  meta="Node 22, iad1"
  readyAt={readyAt}
  cpu={0.34}
  memory={{ used: 1.2e9, total: 2.1e9 }}
  ports={[{ port: 3000, label: "next dev", url: "https://3000-sb-7f3a2c.example.dev" }]}
  logs={logs}
  onStop={stop}
  onRestart={restart}
/>

Logs render in a headerless Terminal, so ANSI from the boot script reads as it does on the machine. statusText replaces the status word while starting, for example Installing dependencies.

Examples

Starting, stopped and failed

Meters read Not running instead of zero when there is nothing to measure. A failure says what went wrong and how to fix it, and offers Start again.

Starting, stopped and failed to start.

Props

Prop	Type	Notes
`name`	`string`	Sandbox id, in mono
`status`	`"starting" \| "ready" \| "stopped" \| "error"`
`statusText`	`ReactNode`	Replaces the status word
`meta`	`ReactNode`	Runtime, region or image
`readyAt`	`number`	Epoch ms. Drives the uptime counter
`cpu`	`number`	0 to 1
`memory`	`{ used, total }`	Bytes
`ports`	`SandboxPort[]`	`{ port, label?, url?, state? }`
`logs`	`string`	Raw output for the logs drawer
`logsOpen`, `defaultLogsOpen`, `onLogsOpenChange`	`boolean`
`fileCount`, `onOpenFiles`		Files shortcut
`onStart`, `onStop`, `onRestart`	`() => void`	Each shows its action when it applies
`error`	`ReactNode`	What failed and how to fix it

Keyboard

Key	Action
`Tab`	Restart, Stop or Start, port links, Logs, Files
`Enter`, `Space`	Toggle the logs drawer

Accessibility

The status word is a polite live region. Ready pairs its green dot with the word, never color alone.
CPU and memory are meter elements with values. Port links say they open in a new tab.
A failure is a role="alert" block.

Motion

The status mark swaps with a 150 ms blur crossfade. Meters scale over 300 ms between readings.
The logs drawer opens with a 200 ms height and opacity transition. Under reduced motion it snaps.