## 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>
Raven in Docker
Build and run the current checkout:
cd docker
docker compose up --build
To run the configured image without rebuilding, use docker compose up --no-build.
Plain docker compose up may reuse or pull an image rather than rebuild local changes.
Then open http://localhost:18793. The local Compose default signs that browser in automatically so Settings > Models is immediately available.
What comes up
One container, two processes:
| process | what it does |
|---|---|
nginx (:80) |
serves the built page from /app/ui-web/dist, proxies /rpc, /auth*, /health, /file, /files/, /oauth/callback to the engine |
| the Raven engine | the RPC gateway on 127.0.0.1:18793 inside the container |
They share a container because the engine binds loopback only
(web.TCPSite(runner, "127.0.0.1", port)), so a proxy in a second container
would have nothing to dial. The image builds the page in a Node stage and the
Python environment with uv sync --frozen, so both halves come from the same
commit.
Signing in
The engine mints a session credential per boot and the page needs a cookie for
it. Compose defaults RAVEN_AUTO_LOGIN=1, so nginx gives a browser loading the
page that credential automatically. This is intended for a locally published
port.
For a remotely exposed deployment, put RAVEN_AUTO_LOGIN=0 in .env.local.
The entrypoint prints a one-time link on startup:
raven-docker: sign in once with this one-time link (replace localhost if you are remote):
http://localhost:18793/auth#<nonce>
The cookie it sets lasts 30 days, and survives a restart -- the engine reloads
the same cookie from /data rather than minting a new one.
The page's raven web advice is for a host install. In a container, mint
another one-time link with:
docker compose exec raven docker-entrypoint.sh signin
Configuring a provider
The engine starts with nothing configured. It says so on the way up:
! no provider is configured yet -- run `raven onboard` for guided setup
Starting anyway. Add a provider in Settings > Models on the page.
Add one in the page's Settings > Models and the next turn uses it -- the provider reads its credentials per call, so nothing needs restarting.
To have a deployment come up already configured, declare one in .env.local
instead:
RAVEN_PROVIDER=anthropic
RAVEN_API_KEY=sk-ant-...
The entrypoint writes that into config on every boot, so where it is set it is the source of truth.
Local providers can be seeded by address without an API key:
RAVEN_PROVIDER=ollama-chat
RAVEN_API_KEY=
RAVEN_API_BASE=http://host.docker.internal:11434
The container always runs raven gateway, including the page, RPC, IM
channels, cron, and the proactivity stack. Its resolving provider re-reads
credentials on every call, which is what makes a provider added in Settings
work on the next turn.
Settings
.env is committed and holds defaults. The service loads the optional,
git-ignored .env.local second for container runtime variables such as provider
credentials and RAVEN_AUTO_LOGIN. Put every credential in .env.local.
Compose interpolation is separate: RAVEN_IMAGE, RAVEN_WEB_PORT,
RAVEN_EXTRAS, RAVEN_PLUGINS, and RAVEN_OFFICE are resolved before the
container starts. Setting them only in the service's .env.local does not
override the image, published port, or build arguments. From this directory,
use shell variables, for example:
RAVEN_IMAGE=raven:local RAVEN_WEB_PORT=18893 docker compose up --build
Or, after creating .env.local, load it explicitly for interpolation too:
docker compose --env-file .env --env-file .env.local up --build
The later file wins; shell environment values override both files.
Data
Everything durable is under /data on the raven-data volume: config.json,
the workspace, sessions, logs and the memory store. Removing the container
keeps it; docker compose down -v does not.
Running a CLI command
Any argument that is not run or signin is handed to the raven CLI:
docker compose exec raven docker-entrypoint.sh provider test anthropic
docker compose run --rm raven status
Notes and limits
- Exposure. The default Compose page automatically grants a Raven browser
session to anyone who can reach its port, so the published port binds
127.0.0.1only. A remote deployment must choose its own bind or proxy and setRAVEN_AUTO_LOGIN=0. nginx also rewrites theOriginheader so the engine accepts a browser that reached it through a published port. That drops a defence-in-depth layer; the session cookie isSameSite=Strict, so an unauthenticated socket is still refused. Publish this port only where you would have published the engine's own. - HTTPS. Not configured here. Terminate TLS in front of this container; the
page picks
wss://fromlocation.protocolon its own. - The TUI is not in this image.
raven tuineeds the Node bundle fromui-tui/, which the image does not build. sandbox. The extra is off by default: inside a container the container is the boundary. Turn it on withRAVEN_EXTRASif you want boxlite as well.- LibreOffice is in the image. The page cannot draw a
.docx,.xlsxor.pptx, so the gateway converts those to PDF to show them; without it every office file in a knowledge base, and every deck, answers the viewer with "LibreOffice is not installed" -- a hosted image telling its user to install something on it. It is the largest thing here, roughly 500 MB with the CJK fonts it needs to render anything but Latin text. Build with--build-arg RAVEN_OFFICE=0, orRAVEN_OFFICE=0in the environment Compose reads, for a deployment that will never preview one.