cauce is a single self-contained Rust binary (engines + UI + AI + archive compiled in; rustls, no OpenSSL). Install with mise, from a GitHub release, or build from a checkout.
mise use -g github:espetro/cauce
cauce serve # UI + API + MCP on http://127.0.0.1:4479This pulls the latest release binary for your platform.
To run once without installing: mise x github:espetro/cauce -- cauce serve.
curl -fsSL https://raw.githubusercontent.com/espetro/cauce/main/install.sh | shIt picks the release tarball for your platform, checks it against SHA256SUMS.txt, and installs cauce to ~/.local/bin.
Set CAUCE_VERSION=v0.9.1 to pin a release or CAUCE_INSTALL_DIR to change the target directory.
Pick the tarball for your platform under https://github.com/espetro/cauce/releases (Linux x86_64 glibc and musl, Linux aarch64, macOS arm64 and x86_64), e.g.:
curl -LO https://github.com/espetro/cauce/releases/download/v0.5.0/cauce-v0.5.0-x86_64-unknown-linux-gnu.tar.gz
tar -xzf cauce-v0.5.0-x86_64-unknown-linux-gnu.tar.gz
./cauce serve # UI + API + MCP on http://127.0.0.1:4479Verify the binary reports the release version:
./cauce --versionmacOS removes the quarantine attribute before first run:
xattr -d com.apple.quarantine ./cauceThe bundled ddgs exec engine is not in the release binaries: it needs a source checkout and python3 (uv sync --project sdk/python --extra ddgs), so it stays a custom-build option.
Disable it in config.toml with the [[engines]] block shown below.
git clone https://github.com/espetro/cauce
cd cauce
mise install # Rust toolchain + cargo-deny + cargo-nextest
cargo install --locked --path crates/cauce-clicargo install puts cauce on ~/.cargo/bin.
Verify:
cauce serve --helpcauce serve # UI + API + MCP on http://127.0.0.1:4479
cauce serve --headless # API + MCP only
cauce mcp # stdio MCP transport, no HTTP listenerDefaults: loopback bind on port 4479 (--bind/--port or CAUCE_SERVER_HOST/CAUCE_SERVER_PORT override), config at ~/.config/cauce/config.toml, data and logs under ~/.local/share/cauce/.
When serving browser discovery URLs behind TLS or a portless proxy, set the canonical external origin in [server].
It is used for the absolute URLs in /opensearch.xml; request Host and forwarded headers are not trusted for this purpose.
If omitted, the configured bind host and port are used over HTTP.
[server]
public_url = "https://search.localhost"The default engine set is the ddgs exec bridge plus every enabled declarative spec (bing, brave; wikipedia ships enabled: false).
Pin a set with CAUCE_ENGINES=bing,brave or [[engines]] entries in config.toml, e.g.
to enable wikipedia:
[[engines]]
id = "wikipedia"
kind = "declarative"
enabled = trueAI answers (/answer, POST /api/answer) are configured under [ai]: provider settings plus the answer loop's budget knobs.
Every key takes a CAUCE_AI_* env override (CAUCE_AI_MAX_TURNS, CAUCE_AI_MAX_SEARCHES, CAUCE_AI_PROVIDER_BUDGET_S, CAUCE_AI_VERIFY) and applies on save without a restart:
[ai]
enabled = true
base_url = "https://openrouter.ai/api/v1"
api_key = "${env:PROVIDER_API_KEY}"
model = "openai/gpt-4o-mini"
protocol = "openai" # or "anthropic"
max_turns = 8 # provider turns before the loop must synthesize
max_searches = 6 # tool calls actually executed per run
provider_budget_s = 60 # per-call provider timeout, seconds (>= 1)
verify = false # reserved for the groundedness verifier (#232)oxmgr supervises long-running apps on this machine; it owns the launchd entries.
Replace any previous oxe entry (command = ".../uv/tools/oxe/bin/oxe") in ~/.config/oxmgr/oxfile.toml with the cauce binary:
[[apps]]
name = "cauce"
command = "/Users/<you>/.cargo/bin/cauce serve"
restart_policy = "always"
crash_restart_limit = 5
stop_timeout = 10
health_cmd = "curl -fsS --max-time 4 http://127.0.0.1:4479/health"
health_interval = 30
health_timeout = 5
health_max_failures = 3Notes:
-
commandneeds the absolute path to the installed binary; oxmgr does not expand~. -
Keep the port at the default 4479 so the existing health check and the portless alias below keep working.
-
An
env = { OXE_BACKENDS = ... }entry left over from the oldoxeapp can be dropped; cauce ignores it. -
The bundled
ddgsexec engine only works whencauceruns from the repo checkout (its relativesdk/python/...path resolves by walking up from the process cwd) and itsuvvenv exists (uv sync --project sdk/python --extra ddgs). Under supervision, disable it in~/.config/cauce/config.toml:
[[engines]] id = "ddgs" kind = "exec" enabled = false command = "python3" args = ["sdk/python/cauce_engine_sdk/ddgs_auto.py"]
(`CAUCE_ENGINES` cannot name `bing`/`brave`: the pin validates against `[[engines]]` entries and built-ins, and embedded specs are only auto-registered when the pin is unset.) To keep ddgs instead, give its `[[engines]]` block absolute `command`/`args` pointing at the venv's python and `ddgs_auto.py`.
Apply the single app (never restart the daemon for a per-app change):
```bash
oxmgr apply ~/.config/oxmgr/oxfile.toml --only cauce
curl -fsS http://127.0.0.1:4479/health
portless exposes the loopback service as https://search.localhost:
portless alias search 4479 --force
portless list | grep search # confirm the routeThis is a fixed-port supervised service, so use portless alias, not portless <name> <cmd> (which is for agent-started dev servers).
MCP and HTTP wiring snippets for Claude Code, Hermes, maki and curl live in agents.md.