## Summary - The missing-boxlite advice told users to run `pip install 'raven[sandbox]'`, which is wrong twice over: the `raven` name on package indexes resolves to an unrelated project, and a global pip install bypasses the uv environment raven actually runs in (#640). - Added `boxlite_install_hint()` to `raven.sandbox`: it resolves the pinned boxlite requirement from the installed distribution metadata (falling back to the bare name when metadata is absent) and renders a copy-pasteable command targeting the running interpreter, e.g. `uv pip install --python /path/to/venv/bin/python boxlite==0.9.5`. - The onboarding screen keeps its translatable line in the zh catalog and prints the command on its own untranslatable line; `build_executor`'s ImportError message uses the same hint. - The two init-failure messages that fire after the boxlite import already succeeded no longer suggest a reinstall; they keep the platform bullets naming the actual causes. ## Type - [x] Fix ## Verification - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [ ] User-facing docs or screenshots are updated when needed Commands run on macOS, Python 3.12, on top of a clean checkout of main: - `uv run pytest tests/test_sandbox_unit.py tests/test_cli_onboard_commands.py tests/test_i18n_boundary.py tests/test_i18n_prompts.py -q` -> 467 passed. The new tests (TestBoxliteInstallHint, TestInitFailureAdvice, one TestBuildExecutor case, one onboard screen case) were each watched failing before the fix. - `uv run --frozen --python 3.12 --all-extras pytest -q` -> 27002 passed, 109 skipped, 21 failed. The 21 failures reproduce identically on unmodified main (verified by stashing this change): `test_agents_research_tools.py` (13), `test_agents_research_verbatim_sink.py` (5), `test_simulation_scenario.py` and `test_simulation_suite.py` (2), `test_rpc_files.py::test_a_host_without_libreoffice_says_so` (1, LibreOffice not installed locally). None touch the changed modules. - `uv run ruff check` and `ruff format --check` on the six touched files -> clean. - `make lint-imports` -> 10 kept, 0 broken. - `make check-source-language` -> pass. ## Risk - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes - User-visible change: three messages read differently (the onboarding hint, the build_executor ImportError, two executor init-failure messages). No API, config, or behavior change beyond the wording. The hint assumes uv on PATH, which every documented install path already requires. - Rollback is a straight revert of this commit. ## Related Issues Fixes #640
Raven operational scripts
Standalone CLIs and admin utilities. Not part of the Raven wheel — these scripts are invoked directly from a checkout and don't ship to end users.
Layout
scripts/
├── README.md This file.
└── boxlite_cli.py Direct CLI for the boxlite microVM library.
When to use
| Script | Purpose | See |
|---|---|---|
boxlite_cli.py |
Manage boxlite OCI images + VMs (pull / ls / create / start / stop / rm / shell). Independent of Raven — works even when no agent is running, can inspect VMs owned by another boxlite home. | docs/sandbox/boxlite_cli.md |
scripts/boxlite_cli.py is complementary to the raven sandbox
sub-command group (in raven/cli/sandbox_commands.py):
raven sandbox …— agent-runtime debug interface (Unix-socket connection to a SandboxDebugServer inside a running Raven process; only sees VMs owned by that process).scripts/boxlite_cli.py …— direct boxlite library CLI (manages images, creates / cleans up VMs, can target any boxlite home dir).
Use raven sandbox when you want to inspect / shell into the VMs
your live agent is currently using. Use scripts/boxlite_cli.py for
everything else (image management, post-mortem cleanup, cross-process
inspection, Raven-not-running scenarios).
Where fixture generators live
Test / benchmark data generators are NOT in scripts/ — they live
alongside the benchmark or test that consumes them. Examples:
benchmarks/skill_evals/fixtures/build_mock_library.py— synthetic SQLite mass-library DB fortest_skill_forge_e2e.pyandskill_evals/run_eval.py.