---
title: Chat UI Agent Runtime
emoji: 🧰
colorFrom: yellow
colorTo: indigo
sdk: docker
short_description: Pinned pi runtime image for chat-ui sandboxes
---

# Chat UI Agent Runtime

Prebuilt Node, git, ripgrep, pi, and reconnect-safe RPC bridge image used by chat-ui Agent
workspaces. The Space itself exposes a small health endpoint; Hugging Face Jobs overrides the
command to start `sbx-server`, then chat-ui spawns `bridge.mjs` inside the dedicated sandbox.

No Hugging Face or provider credential is baked into this image.

The image applies fail-closed patches to the pinned Pi 0.84.2 RPC handler. `replace_queue` performs
an atomic expected-snapshot compare-and-swap over Pi's steering and follow-up queues. Correlated
`extension_ui_response` commands report semantic success only while the native Pi request is still
pending. The image build fails if either upstream handler shape changes, so an upgrade cannot
silently apply a patch to an incompatible release.

`bridge.mjs` explicitly loads `/opt/chat-ui-agent/approval-gate.mjs`. Before every tool call, the
extension reads the bounded policy file at `AGENT_POLICY_PATH` (normally
`/run/chat-ui-agent/policy`). A missing, invalid, or oversized file falls back to `AGENT_POLICY`:

- `auto` confirms remote publishes, uploads, deployments, other likely exit points, and reads of
  credential-bearing files or process-environment values.
- `ask` confirms all writes, edits, shell commands, and sensitive reads.
- `read-only` hard-blocks every write, edit, and shell command; sensitive direct reads still require
  confirmation.

Missing or invalid policy values use `ask`. This live policy file makes “always allow” effective
for the active session without restarting Pi. If the RPC UI is unavailable, gated calls are blocked.
Run the runtime-only tests with `node --test agent-runtime/*.test.mjs` from the repository root.