## Summary - Align English and Chinese documentation for Docker/Compose, sandbox execution, and the in-tree tracing API with verified runtime behavior. - Separate proactivity usage guidance from developer design and implementation details, with configuration, troubleshooting, cost, and safety boundaries. - Update navigation and remove redundant section separators. Keep page URLs unchanged. - Preserve published proactivity section and title anchors in both languages. Use native aliases for same-page content and visible migration links for moved sections, with regression tests. - Clarify Sentinel delivery fallback and menu-selection requirements, tracing-on/off argument handling, headless CLI menu output, and viewer descriptor lookup. Add focused regression coverage without changing runtime behavior. - Clarify the initial frozen baseline and improve Evolver wording in the bilingual site and repository mapping. Keep its structure, navigation, implementation terms, and technical claims unchanged; broader Evolver documentation work is excluded. - No runtime changes. ## Type - [ ] Fix - [ ] Feature - [x] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification Passed on the rebased revision: ```bash uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x # 395 passed uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site # Strict English and Chinese builds passed UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py' UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs git diff --check origin/main...HEAD # All passed ``` - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed Documentation checks also covered bilingual examples and the proactivity JSON configuration schema. A built-HTML audit verified all 110 historical proactivity section fragments and four title fragments, including same-language migration destinations, and found zero broken internal fragment links across 29 HTML pages (672 links). Replaying pre-fix content made all four page compatibility cases fail as expected. The new descriptor-directory test failed on all three documents before their stale paths were corrected. Added coverage exercises tracing on/off, bare-number versus explicit menu selection with incomplete classifier configuration, and discovery-menu dispatch through the real CLI stack's headless sink. Runtime type checks and the full repository test suite were not run; no runtime code changes. No browser click test, live LLM, real-VM, or container end-to-end run was performed. ## Risk Documentation-only, with regression tests. Proactivity navigation changes, but page URLs and historical heading fragments are preserved. An old link to content moved between pages lands on a visible migration entry and requires one click to reach the new section; no JavaScript redirect is needed. Existing queued-nudge policy and external-agent isolation limitations are described, not fixed. Roll back by reverting the documentation and associated test changes; no data migration is involved. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues N/A --------- Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com> Co-authored-by: Codex <noreply@openai.com>
14 KiB
Raven Sandbox — Debug CLI Commands
The raven sandbox command group lets you inspect and interact with the boxlite microVMs that an raven process is using. It connects to a Unix domain socket exposed by the SandboxDebugServer running inside that process, so a running raven with debug mode enabled is required.
These commands are intended for development and troubleshooting (poking at a stuck VM, running ad-hoc diagnostics inside a sandbox, attaching an interactive shell). They are not meant to be enabled in production.
Table of Contents
- Prerequisites
- Connection model
sandbox list/sandbox lssandbox execsandbox shell- VM selection (
--vm) - Errors and exit codes
- Troubleshooting
1. Prerequisites
The debug socket is only created when a raven process is running with
tools.sandbox.debug.enabled = true and a backend other than "none".
Add this to your config.json. The loader accepts JSON, not YAML; invalid JSON
produces a warning and falls back to defaults with sandboxing and debugging disabled:
{
"tools": {
"sandbox": {
"backend": "auto",
"debug": {
"enabled": true,
"socket": "sandbox/debug.sock"
}
}
}
}
| Key | Type | Default | Description |
|---|---|---|---|
debug.enabled |
bool |
false |
Master switch. When false, the debug server never starts and the CLI cannot connect. Ignored if backend = "none". |
debug.socket |
str |
"sandbox/debug.sock" |
Unix socket path. Relative paths are resolved against the Raven data directory; absolute paths are used as-is. The CLI resolves the same value to find the socket. |
debug.maxMessageBytes |
int |
1048576 |
Per-line message cap on the protocol (1 MiB). |
The socket file is created with mode 0600 and is only accessible to the user that started raven. Run the CLI as the same user.
2. Connection model
Each invocation of raven sandbox <subcommand> opens a single connection to the debug socket, sends one command, streams responses, and exits. The protocol is newline-delimited JSON with base64-encoded binary payloads. You do not normally need to know this — the CLI handles framing — but it explains the failure modes:
- Socket missing → no
ravenprocess is running, or it was started withdebug.enabled = false, or the agent process started but its debug server failed to bind (check the agent output for a[Sandbox debug]line). - Permission denied → the socket exists but is owned by a different user.
- Connection refused → the
ravenprocess is exiting or has crashed. Sandbox debug server already has an active client.→ anotherraven sandboxinvocation is currently attached. The server is single-client (see below); wait for the other session to disconnect, or stop it.
The CLI prints a clear message and exits non-zero in each case.
2.1 Single-client policy
The debug server accepts at most one client connection at a time. A second concurrent connection is rejected immediately with the error above; nothing on the server side is disturbed by it. This is intentional:
- It mirrors how a debugger attaches to a running process: one operator, one session.
- Two CLIs racing on the same VM (
execwhile ashellis open, or twoshells into one VM) cause confusing interleaving on PTYs and stream multiplexing — easier to forbid than to coordinate. - It also defends against two
ravenprocesses pointing the samedebug.socketpath at each other: the second process to start sees the live socket from the first and refuses to bind, rather than silently stealing it. (The first process'ssandboxCLI keeps working.)
If you need parallel debug sessions, give each agent a distinct debug.socket path.
3. sandbox list / sandbox ls
List every sandbox VM visible to the running raven process. ls is an alias for list.
raven sandbox list
raven sandbox ls
Output
A Rich table is printed to stdout with the following columns:
| Column | Meaning |
|---|---|
| (first) | * if this VM was created by the connected raven process (owned), - otherwise. |
ID |
The VM identifier returned by boxlite. Use this with --vm for exec / shell. |
State |
VM state. running is highlighted in green; everything else (e.g. stopped, creating) is dimmed. |
Image |
OCI image used for the root filesystem. |
CPUs |
vCPU count. |
Mem MiB |
Memory allocated in MiB. |
Created At |
Creation timestamp, truncated to YYYY-MM-DD HH:MM:SS. |
If no VMs are visible, the command prints No VMs found. and exits 0.
Example
Sandbox VMs
┏━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ ┃ ID ┃ State ┃ Image ┃ CPUs ┃ Mem MiB ┃ Created At ┃
┡━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ * │ vm-abc123 │ running │ ubuntu:22.04 │ 2 │ 2048 │ 2026-05-08 12:34:56│
│ - │ vm-def456 │ stopped │ python:3.11 │ 4 │ 4096 │ 2026-05-07 09:12:30│
└───┴────────────┴─────────┴────────────────┴──────┴─────────┴────────────────────┘
Note
: VMs are not named today, so a
Namecolumn is intentionally omitted; the codebase has TODOs to restore it once naming is supported.
4. sandbox exec
Run a one-shot command inside a sandbox VM and stream its output back to the terminal.
raven sandbox exec [--vm VM_REF] CMD [ARG ...]
Options
| Option | Description |
|---|---|
--vm VM_REF |
Target VM ID. Optional when exactly one VM is running — the server auto-selects it. Required when multiple VMs are running. |
CMD [ARG ...] |
The program and its arguments. Passed through unchanged. Unknown options are forwarded to the program (e.g. raven sandbox exec ls -la /workspace). |
The argument list is captured via allow_extra_args=True and ignore_unknown_options=True, so flags meant for the VM-side program won't be misinterpreted by Typer.
Output streams
- stdout from the VM is written verbatim to the host's stdout (binary-safe, base64-decoded under the hood).
- stderr from the VM is written to the host's stderr, prefixed with
[stderr]so the two streams stay distinguishable when redirected together. - The command exits with the exit code returned by the VM-side process. If the server returns an error, the CLI prints
Error: <message>in red and exits1.
Examples
# Run a single command in the only running VM
raven sandbox exec uname -a
# Pick a specific VM
raven sandbox exec --vm vm-abc123 ls -la /workspace
# Run a Python one-liner
raven sandbox exec python3 -c "import sys; print(sys.version)"
# Capture only stdout (drop the [stderr] prefixed lines)
raven sandbox exec --vm vm-abc123 sh -c 'cat /etc/os-release; ls /missing' 2>/dev/null
Errors
| Condition | Message | Exit code |
|---|---|---|
| No command supplied | Error: a command to execute is required. plus a usage hint |
1 |
| Server-side error | Error: <message> |
1 |
| VM process succeeded | (no extra output) | exit code from the VM process |
5. sandbox shell
Open a fully interactive PTY-backed shell inside a sandbox VM.
raven sandbox shell [--vm VM_REF] [--shell /bin/sh]
Options
| Option | Default | Description |
|---|---|---|
--vm VM_REF |
auto | Target VM ID. Auto-selected if exactly one VM is running. |
--shell PATH |
/bin/sh |
Absolute path to the shell binary inside the VM. Use /bin/bash on images that ship it. |
Behavior
The CLI:
- Sends a
shellcommand to the debug server with the chosen VM and shell binary. - Waits for the server to return a
readymessage before touching the local terminal. If the server returnserrorinstead, the CLI printsError: <message>and exits1without modifying terminal state. - Saves current
termiosattributes, switches the local TTY into raw mode, and registers a non-blocking reader onstdinso every keystroke is forwarded to the VM. - Sends the initial terminal size (
rows,cols) viaTIOCGWINSZ, and re-sends the size on everySIGWINCH(window resize). The signal is bounced through the asyncio loop, socreate_taskand writer access happen on the loop thread. - Streams the VM's stdout back into the local terminal verbatim (binary-safe).
- On
exit, restores terminal attributes, removes the stdin reader, restores the previousSIGWINCHhandler, closes the socket, and propagates the VM-side exit code as its own.
If the server-side process emits an error mid-session, the CLI restores the terminal before printing the red error message, so the message is readable.
Examples
# Drop into /bin/sh inside the only running VM
raven sandbox shell
# Use bash and target a specific VM
raven sandbox shell --vm vm-abc123 --shell /bin/bash
To exit the shell, run exit or press Ctrl-D inside the VM, or close the local terminal. The CLI restores your terminal as the connection closes.
Tip
:
Ctrl-Cis forwarded to the VM as0x03because the local terminal is in raw mode — it interrupts the foreground program inside the VM, not the CLI. To kill the CLI itself from outside, send itSIGTERMfrom another terminal.
EOF / Ctrl-D: Interactive
Ctrl-Dis forwarded as a raw0x04byte and interpreted asVEOFby the VM-side PTY's line discipline (matchesdocker exec -it). When the local stdin is a pipe or file and reaches EOF, the CLI synthesises one final0x04byte before disconnecting so the VM-side shell terminates cleanly instead of waiting for input that will never arrive. If a particular image's PTY is configured to suppressVEOF, runexitinstead.
Idle disconnect: Closing the terminal (or hitting Ctrl-C in another terminal) without typing
exitis now safe — the server detects the client is gone, kills the VM-side shell, and releases the single-client slot. Previous releases could leave an orphanshrunning inside the VM in this case.
6. VM selection (--vm)
exec and shell take an optional --vm argument:
- Omit
--vmwhen exactly one VM is running. The server picks it automatically. - Pass
--vm <id>to target a specific VM by ID (as shown insandbox list). - The flag also accepts a name in the protocol (
vm_ref) for forward compatibility, but VMs are unnamed today, so practically only IDs work.
If --vm is omitted and zero or more-than-one VMs are running, the server returns an error and the CLI exits 1.
7. Errors and exit codes
All commands share the same connection-time error handling:
| Situation | Output | Exit code |
|---|---|---|
| Socket file missing | Debug socket not found at <path>. plus a hint to enable sandbox.debug.enabled=true and to check the agent log for a debug-start failure |
1 |
| Socket exists but unreadable/unwritable | Cannot connect to debug socket at <path>: permission denied |
1 |
Connect failed (ECONNREFUSED, ENOENT, OS error) |
Cannot connect to debug socket at <path>: <reason> |
1 |
| Another client already attached | Error: Sandbox debug server already has an active client. … |
1 |
Server returned {"type": "error", "message": ...} |
Error: <message> |
1 |
list succeeded |
table or No VMs found. |
0 |
exec succeeded |
streamed stdout/stderr | exit code of the VM-side process |
exec client disconnected mid-run |
(no client output) — server kills the VM-side process | n/a |
shell succeeded |
interactive session | exit code of the VM-side shell |
8. Troubleshooting
Debug socket not found at /…/sandbox/debug.sock
The raven process is not running, or it was started with sandbox.debug.enabled = false, or with sandbox.backend = "none" (debug mode is intentionally ignored when there are no VMs to inspect — see agent/loop.py), or the debug server failed to bind. If the agent is running, look in its log/output for a [Sandbox debug] line — most commonly this happens because another raven process is already listening on the same socket path. Either stop the other process or set tools.sandbox.debug.socket to a different path for this one.
Cannot connect to debug socket at … : permission denied
The socket is created with mode 0600 and is owned by the user that launched raven. Run the CLI from that same user (or via sudo -u <user>).
Error: a command to execute is required.
You called raven sandbox exec without a command. Append the program and its arguments after --vm <id>.
exec shows no output, then exits 0
The command ran successfully and produced nothing. Try raven sandbox exec sh -c 'echo hi' to confirm the channel works.
shell leaves the terminal garbled after a crash
The cleanup path normally restores termios and SIGWINCH. If the CLI was killed before cleanup ran (e.g. kill -9), run reset (or stty sane) to recover.
Message too large.
A single protocol message exceeded sandbox.debug.maxMessageBytes (default 1 MiB). For exec, this only happens with extremely large single chunks of stdout/stderr; redirect output to a file inside the VM instead, or increase maxMessageBytes.