## Summary Behind a TLS-inspecting corporate proxy, or against a company-hosted gateway signed by a private CA, `raven onboard` failed with `CERTIFICATE_VERIFY_FAILED` even with the corporate root installed in the operating system (#637). httpx, LiteLLM and the OpenAI SDK verify against certifi's bundled roots unless told otherwise, so the operating-system store was never consulted on the paths that reach a model. aiohttp, urllib and websockets read OpenSSL's defaults instead, so one process trusted two different sets of roots depending on which client made the call. What changes: - `raven/security/tls.py` (new): `use_system_ca()` injects truststore, so every TLS context built afterwards is verified by the operating system (CryptoAPI on Windows, the Security framework on macOS, OpenSSL's default paths on Linux). A bundle a caller loads into a context is still honoured: on Linux it joins the store, on macOS its roots become extra anchors, on Windows it is tried when the system roots fail. So every root trusted before stays trusted. `RAVEN_NO_SYSTEM_CA=1` opts out, parsed like `RAVEN_NO_UPDATE_CHECK`. - `raven/cli/entry.py` (new) is now the entry of both the console script and `python -m raven`, the form the web supervisor starts its gateway with. It switches trust before importing the CLI, because the CLI's imports reach aiohttp (through the sub-agent backends), and aiohttp builds its default context when it is imported. `raven/cli/commands.py` no longer starts the CLI when run as a script, which skipped the switch; pointing it at the entry would not have helped, since by then its own imports have built aiohttp's context. - The provider probe names a certificate that fails verification `certificate_untrusted` instead of `network_error`. It checks for that ahead of the proxy branch: through a proxy that answered the tunnel, a refused certificate used to be reported as `proxy_unreachable`. The Codex check (its backend's list of the account's models), MiniMax's token renewal (which reported `oauth_token_missing`) and the sub-agent key prompt's probe name it too. LiteLLM's Copilot token exchange and its ChatGPT renewal drop the handshake error before Raven sees it, so those still read as the credential. - The three surfaces that read the probe say so. `raven onboard` and `raven provider test` no longer send the reader to check the network, proxy or VPN; their hints name the three causes: a CA to add to the system certificate store; macOS and Windows refusing a certificate by their own rules even when `SSL_CERT_FILE` trusts its CA, which `RAVEN_NO_SYSTEM_CA=1` turns off; and an expired certificate, or one for another host, which is the server's to fix. `raven onboard` offers the menu a network error gets (re-entering the key cannot fix a certificate); the web Settings page has its own line, in English and Chinese, in `i18n/messages.json` and the TUI's catalogue generated from it. - The RPC contract's description of the model catalogue's `status` (`rpc-schema/openrpc.json` and both generated clients) now lists the probe's real words. It named `unauthorized`, which the probe never returns (a 401 or 403 is `invalid_key`), and missed `proxy_unreachable` as well as the new status. - The Codex provider no longer retries a request whose certificate failed verification with verification turned off (`verify=False`). The second attempt carried the ChatGPT OAuth bearer token and the whole conversation to whoever presented the certificate (a captive portal, a hostile network, a proxy that re-signs TLS), and on a network like the one in #637 it is what would keep Codex working unverified while every other provider fails. The retry dates from the initial import; `_request_codex` loses the `verify` parameter that existed only to carry it. - `raven upgrade` and the page's Update verify against the same store as the release lookup. The upgrade helper runs on the base interpreter, outside the tool environment that holds truststore, and fetched the release lists with urllib's default context; uv fetched the rest with its bundled roots. When the spawning process itself verifies against the system store, it now copies truststore into a fresh temporary directory and hands the helper its path, as it hands over the marker path; one that opted out, or never went through `cli.entry`, hands over nothing and needs no truststore to say so. The helper loads the copy before its first download and deletes it, and gives `UV_SYSTEM_CERTS` (and `UV_NATIVE_TLS`, which older uv reads) to uv's own calls only, so the Raven it relaunches inherits neither. A copy, because `inject_into_ssl()` imports requests and urllib3 wherever it finds them, and the tool environment's belong to what uv is about to rewrite. - Quick Start, in both languages, gains a section on corporate proxies and private CAs: WSL2 does not see the Windows store, and the EverOS memory server and Node-based agents run as separate programs that need `SSL_CERT_FILE` and `NODE_EXTRA_CA_CERTS` in the shell profile. `SSL_CERT_FILE` must name a complete bundle that exists, since httpx refuses to start with a missing one: `/etc/ssl/certs/ca-certificates.crt` on Debian, Ubuntu and WSL, and one built from `/etc/ssl/cert.pem` on macOS. A note says macOS and Windows apply their own certificate policy and names `RAVEN_NO_SYSTEM_CA=1` as the way back. The LiteLLM warning in the issue ("Failed to fetch remote model cost map ... CERTIFICATE_VERIFY_FAILED", with `SSL_CERT_FILE` exported) is not LiteLLM building its own store. That fetch is a plain `httpx.get`, which reads `SSL_CERT_FILE`, and the variable replaces the whole trusted set: with a corporate-only PEM the gateway verifies while raw.githubusercontent.com, signed by a public root, no longer does. Measured with a private CA: corporate-only PEM, warning; certifi plus the corporate root, remote fetch succeeds. Not covered, by construction: the EverOS server is a separate `everos` executable and Node-based agents are not Python, so an injection in this process cannot reach them. The new docs section gives them their environment variables. `uv.lock`: adding truststore re-resolved the lock (uv 0.11.25, revision 3 kept). Besides the truststore entries, five packages' dependency edges lose a marker: matrix-nio, h2, aiohttp-socks, aiologic and culsans. Each dropped marker is implied by the only path that reaches its package (matrix-nio, and through it h2 and aiohttp-socks, only where `sys_platform != 'win32'`; culsans and aiologic only below Python 3.13), so the resolved set is unchanged on every platform. uv 0.12.23 produces the same edges and also rewrites the lock to revision 5, so it was not used; both versions accept the committed lock under `uv lock --locked`. ## Type - [x] Fix - [ ] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification Red first, on the base: the end-to-end `raven provider test custom` against a gateway whose root only the stand-in system store holds exits 1 with `network_error ... unable to get local issuer certificate` under both launch forms, and its opted-out twin prints "Check network / firewall / VPN settings"; the probe test returns `network_error`, and through a CONNECT proxy `proxy_unreachable`; the onboarding menu offers `rekey` for a certificate failure; the web note falls to `probe_unknown`; and the Codex test's endpoint receives `Bearer tok-secret`, with the captured log line `SSL certificate verification failed for Codex API; retrying with verify=False`. Mutations, each applied and then restored byte for byte: - the entry no longer switching trust: both end-to-end trust cases fail; - the switch moved after the CLI import: only `test_trust_is_settled_before_the_cli_builds_a_context` fails; - the classifier accepting any `ssl.SSLError`: the plain-HTTP case fails; - the certificate check placed after the proxy branch: the proxy case fails. Review round two, red first at the round-one head: against an endpoint signed by a root no store holds, the Codex check returned `network_error`, MiniMax's token renewal `oauth_token_missing` and the sub-agent key probe `network_error`; both hint tests failed on the missing opt-out; the guard scan found `raven/cli/commands.py`; and the upgrade tests found nothing handed over. Round-two mutations, each applied and then restored byte for byte: - the classifier matching `CERTIFICATE_VERIFY_FAILED` in the message: the new macOS and Windows cases fail (282 of 282 stayed green before them); - 17 single-construct mutants of the upgrade hand-over (not switching, not putting the copy on the path, keeping it, hiding a failed load, leaving the path in the environment, not telling uv, overwriting a uv setting the user made, dropping the older uv name, telling uv without a copy, uv not given its environment, passing on an inherited path, importing truststore instead of reading whether this process switched, handing over without that check, handing over always, handing over no copy, and keeping a copy no helper started, at each spawn site): each fails at least one test; - the copy failure's warning and its cleanup: each fails the copy-failure test. Commands and results, at the head after rebasing onto `main`. The commits `main` gained since round one touch none of this branch's lines: `git range-diff` shows every commit unchanged, and the aggregate patch-id is the same before and after. - The touched Python test files (`tests/test_security_tls.py`, `tests/test_cli_system_ca.py`, `tests/test_config_update_providers.py`, `tests/test_cli_onboard_commands.py`, `tests/test_cli_provider_commands.py`, `tests/test_cli_subagent_setup.py`, `tests/test_updates_upgrade.py`, `tests/test_openai_codex_provider.py`), the Codex provider's neighbours (`tests/test_providers_first_byte_budget.py`, `tests/test_provider_protocol.py`) and the i18n tests, in full: 1010 passed. - Full suite with branch coverage, `pytest -q -p no:randomly --cov=raven --cov=raven_everos --cov-branch` on the all-extras environment with the box proxy variables unset: 2 failed, 27750 passed, 119 skipped. Both failures fail the same way on a clean tree of the new merge base under the same interpreter, so neither is introduced; they are local to this box (an `npm` on its PATH, and running as root): - `tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for` - `tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing` - `scripts/coverage_gate.py diff --base-ref origin/main --threshold 90` over that run: 100.00% (57/57 executable changed lines). - `tests/integration/test_cli_upgrade_real_uv.py`, which CI runs only in the Windows self-upgrade job (`--noconftest`): 3 passed locally. Its fixture calls the handoff without `cli.entry`; the `system store` variant switches first, as `cli.entry` does, so that job runs the whole hand-over on Windows, and the fixture prints what it handed over so neither variant passes without its branch running. - `ruff check`, `ruff format --check`, `ty check` over the changed modules, `lint-imports` (10 contracts kept), `deptry raven`: clean. - Repository gates over `origin/main...HEAD`: `check_source_language.py`, `check_large_files.py` and `check_commit_messages.py` exit 0. - Generated files on the rebased tree, where `main` had also changed the RPC schema, the message catalogue and their generated copies: `gen-i18n.mjs --check` and `gen-rpc-types.mjs --check` (ui-tui) and `gen-rpc-client.mjs --check` (ui-web) exit 0. - Round two changes no file under `ui-web`, `ui-tui` or `rpc-schema`; these were measured at round one: - ui-web, `node node_modules/vitest/vitest.mjs run src/features/settings/SetupBodies.test.tsx scripts/gates/i18n-keys.test.mjs`: 33 passed; `scripts/gates`: 46 files, 205 passed; `tsc --noEmit` clean, its `--listFiles` resolving the edited files inside this tree; ESLint clean on the three files. - ui-tui, the steps of TUI checks: ESLint 0 errors; `lint:rpc` and `lint:i18n` pass; `tsc --noEmit` clean; the build passes; `vitest run` has 9 failures in 4 files (renderer and typing-burst tests), the same 9 that fail on a clean worktree of the merge base on this box, so none is introduced. - RPC contract: `node scripts/gen-rpc-client.mjs --check` (ui-web) and `node scripts/gen-rpc-types.mjs --check` (ui-tui) exit 0, each generated file differing from the base by the one description line; the 9 Python test files that read the schema, 798 passed. - Docs: `mkdocs build --strict` clean, with the new paragraphs on the English and Chinese pages; `tests/test_docs_site.py` and `tests/test_living_docs.py` pass in the full suite. The end-to-end cases run on Linux only. They stand the system store in with OpenSSL's directory store through `SSL_CERT_DIR`, and name a bundle of public roots in `SSL_CERT_FILE` so that httpx cannot pass by reading `SSL_CERT_DIR` itself. Verification on macOS and Windows was read from truststore 0.10.4's source, not run. The upgrade helper's tests share the limit: on Linux truststore and the standard library read the same store, so they show the hand-over (the copy loads on the base interpreter under `-I` before the first download, and uv alone is told), not the Keychain difference it exists for. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk - Every Raven process started as `raven` or `python -m raven` now trusts the operating system's roots in addition to what each library bundles. For those processes `SSL_CERT_FILE` adds to the trusted set instead of replacing it; someone using it to narrow trust to one private root keeps that root but also trusts the system store. - On macOS and Windows the system verifier applies its own certificate policy as well. A private certificate that OpenSSL accepted from `SSL_CERT_FILE` can be refused there if it breaks that policy; `RAVEN_NO_SYSTEM_CA=1` restores OpenSSL's verification. - On macOS and Windows truststore also verifies the client's chain on server-side contexts, refusing a client that sends none. Raven builds no server-side TLS context: it serves plain HTTP on localhost. - Upgrades verify their downloads the way the release lookup does: on macOS that includes Apple's certificate policy, which the helper's OpenSSL did not apply. uv is told to use the system store only for the upgrade's own calls, and a `UV_SYSTEM_CERTS` or `UV_NATIVE_TLS` the user set is kept. - Behind a proxy that re-signs TLS, Codex requests now fail with the certificate error instead of continuing unverified. Trusting the proxy's root, in the system store or in a complete bundle named by `SSL_CERT_FILE`, is the remedy. - Startup: about 100 ms warm and 270 ms cold, measured on Linux, mostly truststore importing urllib3 and requests to patch their references. - Rollback: `RAVEN_NO_SYSTEM_CA=1` restores the previous trust per process, and an upgrade started under it hands its helper and uv nothing; the Codex change has no switch, by design. Reverting the squash commit removes both. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues Fixes #637 --------- Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
5.7 KiB
First run
Quick Start
Install Raven, configure a model provider, and start using the WebUI.
Install Raven
Choose the installer for your operating system. It sets up a managed Raven
environment and adds the raven command to your shell.
Linux, macOS, or WSL2
curl -fsSL https://raven.evermind.ai/install.sh | bash
Windows PowerShell
irm https://raven.evermind.ai/install.ps1 | iex
Windows PowerShell 5.1, the version built into Windows, cannot follow that URL's
redirect and stops with (308) Permanent Redirect. If you see that error, use the
direct installer URL:
irm https://raw.githubusercontent.com/EverMind-AI/Raven/refs/heads/main/install.ps1 | iex
From a source checkout
To develop Raven or try unreleased changes, clone the repository and run the installer locally:
git clone https://github.com/EverMind-AI/Raven.git
cd Raven
./install.sh
Running the local install.sh installs Raven and its bundled plugins in
editable mode, so they use your working tree. The TUI and WebUI are also built
from that checkout. Piping the installer to a shell installs the published
wheel, even from inside a clone. To select a local source directory for a piped
installation, set RAVEN_LOCAL_SRC=<dir>.
Update Raven
Update Raven the same way you installed it. Running an installer again stops
the running WebUI and finishes by starting a new one in the foreground: press
Ctrl-C to stop it, then run raven web to keep Raven running in the
background. Your settings and conversations in ~/.raven are kept.
Update from the page
When the bottom of the sidebar says a new version is available, click it and
confirm. Raven shows the download's progress, installs the new version,
restarts, and the page reloads by itself. Your settings and conversations are
kept. While a turn, a sub-agent or a question waiting for an answer is still
running, including in an IM channel, the page asks you to let it finish first.
A Raven started by hand with raven gateway or raven web --foreground has
nothing to restart it, so update that one from the command line below.
Update a one-line install
Run the same installer again. It installs the newest release over the current one and starts the WebUI again when it finishes.
To update from the command line instead:
raven web --stop
raven upgrade
On Linux and macOS raven upgrade runs the install in the foreground and
returns when it is done. On native Windows it hands the install to a separate
helper and returns at once; wait for the helper's completion message before
going on. Then start Raven again:
raven web
raven upgrade installs the newest release but does not restart a Raven that
is already running, so stop the WebUI before you upgrade and start it again
afterwards. To check whether a newer release exists without installing it, run
raven upgrade --check.
Update a source checkout
Pull the latest changes and run the local installer again (.\install.ps1 in
PowerShell):
git pull
./install.sh
The installer reinstalls the checkout in editable mode, rebuilds the TUI and
WebUI only when their sources have changed, and starts the WebUI again.
raven upgrade does not update a source checkout, because the code to update
is the checkout itself.
Configure the first provider
Run the guided setup after installation:
raven onboard
Follow the prompts to configure a model provider and choose which built-in agents to enable. You can later add or update providers in the WebUI under Settings > Model providers.
Behind a corporate proxy or private CA
Raven checks HTTPS certificates against your operating system's certificate
store, so a root certificate your IT department installed there is trusted
without extra settings. If a provider check reports certificate_untrusted,
add the root certificate that signs your gateway or proxy to that store.
On WSL2 the Linux distribution keeps its own store and does not see the certificates installed in Windows. Import the root once inside WSL:
sudo cp corporate-ca.pem /usr/local/share/ca-certificates/corporate-ca.crt
sudo update-ca-certificates
The EverOS memory server and Node-based agents run as separate programs that read environment variables instead. Export these in your shell profile, not only in the current terminal, so every process Raven starts receives them:
export SSL_CERT_FILE=/path/to/ca-bundle.pem
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
SSL_CERT_FILE replaces the whole list of trusted roots, so point it at a
complete bundle that also holds your corporate root, and never at a path that
does not exist: httpx, which model calls and provider checks go through,
refuses to start with one. On Debian, Ubuntu and WSL,
/etc/ssl/certs/ca-certificates.crt is that bundle once
update-ca-certificates has run. On macOS, build one first:
cat /etc/ssl/cert.pem corporate-ca.pem > ~/ca-bundle.pem
On macOS and Windows the operating system also applies its own certificate
policy; macOS, for example, refuses a server certificate valid for more than
825 days, or one not marked for server authentication, even when it trusts the
root. To go back to each library's own certificate list, export
RAVEN_NO_SYSTEM_CA=1 in the same profile.
Start Raven
Launch the WebUI with the Raven engine running in the background:
raven web
The local page opens at http://127.0.0.1:18792. To stop the background
service, run:
raven web --stop
See Self-Hosting for Docker deployment and instructions for building and running the server from source.