Skip to content

Latest commit

 

History

History
169 lines (123 loc) · 5.92 KB

install.md

File metadata and controls

169 lines (123 loc) · 5.92 KB

Install

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.

Install with mise

mise use -g github:espetro/cauce
cauce serve     # UI + API + MCP on http://127.0.0.1:4479

This pulls the latest release binary for your platform. To run once without installing: mise x github:espetro/cauce -- cauce serve.

Install with the script

curl -fsSL https://raw.githubusercontent.com/espetro/cauce/main/install.sh | sh

It 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.

Install a release binary

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:4479

Verify the binary reports the release version:

./cauce --version

macOS removes the quarantine attribute before first run:

xattr -d com.apple.quarantine ./cauce

The 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.

Build and install

git clone https://github.com/espetro/cauce
cd cauce
mise install            # Rust toolchain + cargo-deny + cargo-nextest
cargo install --locked --path crates/cauce-cli

cargo install puts cauce on ~/.cargo/bin. Verify:

cauce serve --help

Run

cauce serve                # UI + API + MCP on http://127.0.0.1:4479
cauce serve --headless     # API + MCP only
cauce mcp                  # stdio MCP transport, no HTTP listener

Defaults: 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 = true

AI 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)

Supervision (oxmgr / launchd)

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 = 3

Notes:

  • command needs 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 old oxe app can be dropped; cauce ignores it.

  • The bundled ddgs exec engine only works when cauce runs from the repo checkout (its relative sdk/python/... path resolves by walking up from the process cwd) and its uv venv 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 alias

portless exposes the loopback service as https://search.localhost:

portless alias search 4479 --force
portless list | grep search   # confirm the route

This is a fixed-port supervised service, so use portless alias, not portless <name> <cmd> (which is for agent-started dev servers).

Agent wiring

MCP and HTTP wiring snippets for Claude Code, Hermes, maki and curl live in agents.md.