| 1 | # Environment-specific caveats |
| 2 | |
| 3 | Standard build/test/run commands live in `AGENTS.md` and `CONTRIBUTING.md`. |
| 4 | This file records only the non-obvious quirks of particular environments, so |
| 5 | they do not cost context on machines that will never hit them. |
| 6 | |
| 7 | ## Cursor Cloud VMs |
| 8 | |
| 9 | - **System build dep:** the build needs `libdbus-1-dev` (pulled in by |
| 10 | `crates/secrets` for the OS keyring). It is installed by the startup update |
| 11 | script; if a `cargo build` fails with a `dbus`/`pkg-config` error, that dep is |
| 12 | missing. |
| 13 | - **`rustup default` must be set:** some tests and runtime paths spawn shells in |
| 14 | temp dirs *outside* this checkout (e.g. `run_verifiers_background_*`, sub-agent |
| 15 | worktrees). Those spawned shells only see the repo's `rust-toolchain.toml` |
| 16 | override while inside `/workspace`, so without a global default they fail with |
| 17 | "rustup could not choose a version of rustc to run". The update script runs |
| 18 | `rustup default stable` to fix this. |
| 19 | - **Known env-specific test failures at `/workspace` (not code bugs):** because |
| 20 | the checkout sits directly under `/`, two `codewhale-tui` subagent tests fail |
| 21 | here — `git_repo_root_reports_attempted_paths_when_no_repo_found` (cannot |
| 22 | create a temp dir in the unwritable parent `/`) and |
| 23 | `create_isolated_worktree_reports_friendly_error_when_no_repo_found` (walking |
| 24 | up to `/` discovers `/workspace` itself as a repo). Both pass when the repo is |
| 25 | checked out under a normal, writable parent. |
| 26 | |
| 27 | ## Running the agent without provider API keys |
| 28 | |
| 29 | Point CodeWhale at any local OpenAI-compatible endpoint via the keyless |
| 30 | `vllm`/`ollama`/`sglang` providers: |
| 31 | |
| 32 | ```sh |
| 33 | CODEWHALE_PROVIDER=vllm VLLM_BASE_URL=http://127.0.0.1:8000/v1 VLLM_MODEL=<id> \ |
| 34 | codewhale exec --auto "..." |
| 35 | ``` |
| 36 | |
| 37 | `codewhale exec` (add `--auto` for tool use) is the non-interactive path to |
| 38 | exercise the full agent loop. |
| 39 | |
| 40 | ## Dispatcher needs its sibling |
| 41 | |
| 42 | The `codewhale` binary shells out to a sibling `codewhale-tui` in the same |
| 43 | directory (both land in `target/debug` after a build). If they are not |
| 44 | co-located, set `DEEPSEEK_TUI_BIN` to the `codewhale-tui` path. |
| 45 |