| 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 | ## Consolidated runtime commands |
| 41 | |
| 42 | The current `codewhale` binary runs the TUI in-process. Release installers copy |
| 43 | the same bytes to the optional `codew` short command; no sibling |
| 44 | `codewhale-tui` executable is required. `DEEPSEEK_TUI_BIN` remains a legacy |
| 45 | replay/migration setting, not a current install requirement. |
| 46 |