Languages / 语言: English (this page) · 中文

CrabMate

CrabMate is a Rust-based AI agent that speaks OpenAI-compatible chat/completions to backends such as DeepSeek, MiniMax, Zhipu GLM, Moonshot Kimi, and local Ollama.

It ships HTTP serve (API-only by default) plus ops CLIs. Official Web UI, Desktop/Android, and remote terminal (crabmate-tui) live in crabmate-client (local checkouts default to sibling ../crabmate-client; Playwright forwarding honors CRABMATE_CLIENT_DIR). In-process repl / chat / tui command entries are removed (use Client crabmate-tui; see ADR).

Path A (repo split): this repository maintains Server (serve, contracts, ops CLI). Official clients are in crabmate-client (ADR).

Contents

• Overview
• Common subcommands
• Build, run, and packaging
  • Makefile (recommended)
  • Backend
  • Web frontend
  • Official Client (Desktop / Android)
  • Install and release artifacts
  • Maintainer QA
• Documentation index
• Backend models
• Environment variables
• Deployment and security
• Project structure

Overview

• Chat and tools: OpenAI-compatible chat/completions; built-in workspace files, run_command (allowlist; defaults include bash/sh—glob/$VAR/~ run via bash -c on the joined script; Web re-approves standalone &&/| even if bash is allowlisted; approval shows that script; argv outside the workspace or path-traversal-shaped .. defaults to approval via allow_external_path_with_approval—git A..B is not treated as traversal), HTTP, web search (default worbrow local browser, no API key; optional Brave/Tavily), workspace code search (keyword + optional semantic/embeddings). Full list: docs/en/TOOLS.md. Subprocess tool output is truncated by command_max_output_len (embedded default 512KiB); see config/tools.toml and docs/en/CONFIGURATION.md.
• Web UI (Client): built and shipped from crabmate-client; this repo’s serve defaults to API-only; host a SPA with --with-web plus CM_WEB_STATIC_DIR (or probed Client frontend/dist). Sessions, workspace picker / project pool, editor mode, PR views, terminal-style chat stream, Ask/Plan/Act, and settings—see Client README and docs/en/CLI.md. Tools and @relative-path apply only after a workspace is selected.
• Terminal: Official remote client is crabmate-tui in crabmate-client (HTTP/SSE to serve; LLM keys stay on the client). In-process repl / chat / tui are hard-deleted (D2.2—docs/design/client_shell_split.md §2.5). serve is HTTP API-only by default (optional --with-web). Streaming SSE: docs/en/SSE_PROTOCOL.md.
• Sessions and export: by default Web serve persists under <workspace>/.crabmate/conversations.db; clear conversation_store_sqlite_path to disable. Web or CLI save-session (alias export-session) → JSON/Markdown; shape in docs/en/CLI.md.
• Advanced (skip by default): staged-plan timeline, clarification UI, thinking_trace, long-term memory, living docs, MCP, workspace plugins/*.json: docs/en/CONFIGURATION.md, docs/en/TOOLS.md.

Common subcommands

With no subcommand, clap requires an explicit command (e.g. serve). Prefer serve + Client crabmate-tui. Common globals: --config, --workspace, --no-tools, --llm-context-tokens, --log (see crabmate --help).

Full flags, HTTP routes, man crabmate: docs/en/CLI.md.

Build, run, and packaging

Prerequisites: Rust 1.85+ (edition 2024). Official UI is in the Client repo (Trunk / wasm32). More: AGENTS.md.

Makefile (recommended)

make help              # list targets
make all / all-dev     # backend-release / backend
make backend           # cargo build -p crabmate
make package           # server-only tar.gz + optional .deb → dist/ (no UI)
make clean             # clean target and dist/

UI: cd ../crabmate-client && make frontend (clone crabmate-client as a sibling first). make package / package-tar / package-deb are server-only (API-only by default; use --with-web + CM_WEB_STATIC_DIR to host SPA). Desktop / Android: crabmate-client.

Backend

# Debug
cargo build
./target/debug/crabmate serve            # API-only by default
./target/debug/crabmate serve --with-web # host SPA (needs CM_WEB_STATIC_DIR or probed dist)
# or: API_KEY=… ./target/debug/crabmate serve

# Release
cargo build --release
./target/release/crabmate serve

# Optional: Ubuntu 24.04 toolchain image (dev + `make package`; glibc 2.39; not a runtime)
# docker build -t crabmate-dev .          # add --network=host only if DNS fails
# docker run --rm -it -v "$PWD":/workspace -w /workspace crabmate-dev
# make package-docker                     # → dist/*.tar.gz and dist/*.deb on the host

serve Web API auth (CM_WEB_API_BEARER_TOKEN, etc.): Deployment and security. Cloud API_KEY: Environment variables (or Client Web Settings / client_llm on requests).

Web frontend

Official UI source: frontend/ in crabmate-client (path A Phase 4.2). Local default: sibling ../crabmate-client.

cd ../crabmate-client && make frontend
export CM_WEB_STATIC_DIR="$PWD/frontend/dist"
cd ../crabmate_agent && cargo run -- serve --with-web

API-only (default): serve. UI pointers: docs/frontend/.

Official Client (Desktop / Android)

Canonical repo: crabmate-client (path A; ADR; local sibling ../crabmate-client).
This repo removed desktop-tauri/ / mobile-tauri/ / crates/crabmate-connect (Phase 4.1).

The shell does not spawn serve: start crabmate serve, then enter URL + Web API Bearer on the Client connect page.

cd ../crabmate-client
make desktop-release    # Linux .deb (no serve sidecar)
# or make apk / cargo tauri dev — see Client README

Compat matrix: docs/design/client_compat_matrix.md.

Install and release artifacts

Maintainer QA

• Cargo features: default server (includes protocol, web, mcp); opt-in fastembed, project_metrics, docker_sandbox, gen-man. Examples: cargo build --features fastembed, --features project_metrics, or --all-features. In-process repl/tui features removed (D2.2; use Client crabmate-tui). See root Cargo.toml [features] and AGENTS.md.
• fmt / clippy / test, pre-commit, SSE, E2E: docs/en/TESTING.md (includes ./scripts/check-sse-protocol.sh). CI also runs make package (server-only tar.gz + .deb smoke).

Documentation index

More: backlog, roadmap, frontend drafts—under docs/ (docs/中英文文档对照.md).

Maintenance: keep user-visible docs in sync; conventions in docs/en/DEVELOPMENT.md.

Backend models

POST {api_base}/chat/completions (OpenAI-compatible). Under [agent] set api_base, model, max_tokens (embedded default 4096), llm_http_auth_mode; with bearer, use env API_KEY—never commit real keys.

Local checks: crabmate doctor (no API_KEY), probe / models. Vendor knobs: docs/en/CONFIGURATION.md. Vendor behavior is defined by provider docs.

Environment variables

Other CM_* (skills, staged planning, etc.): docs/en/CONFIGURATION.md.

Deployment and security

• Listen: default 127.0.0.1; 0.0.0.0 needs web_api_bearer_token or an explicit insecure switch (docs/en/CONFIGURATION.md).
• LLM API Key: Client stores keys locally and sends client_llm.api_key. Process env API_KEY remains an optional serve / ops fallback.
• Web API: embedded default web_api_require_bearer = false—serve may start without a shared secret; with true, require non-empty CM_WEB_API_BEARER_TOKEN (or TOML / crabmate web-bearer set). When the token is set, send Authorization: Bearer … or X-API-Key: …. Browsers must save the same value under Settings → Web API shared secret (localStorage crabmate-api-bearer-token)—not the LLM API_KEY. Cross-origin static UI: set API base; official shell Origins are allowed by default—add CM_WEB_CORS_ALLOWED_ORIGINS only for extra browser Origins. Smoke: docs/design/client_turn_smoke_runbook.md §9. Temporary local skip: unset the secret and bind 127.0.0.1, or clear it and set CM_ALLOW_INSECURE_NO_AUTH_FOR_NON_LOOPBACK=true before 0.0.0.0. Prefer web_api_require_bearer = true on exposed networks. Details: docs/en/CONFIGURATION.md.
• Other: Web Settings → Save all persists via /user-data; workspace must stay under allowed roots. Debug / GET /web-ui: docs/en/DEBUG.md.
• Personal VPS (TLS reverse proxy): docs/个人VPS部署指南.md (Chinese; 127.0.0.1 + Bearer + Caddy/Nginx).

Project structure

Architecture overview: docs/en/DEVELOPMENT.md. GET /status for full runtime status; Web shell uses GET /status?view=shell. More: docs/en/DEBUG.md.

• Single crate: crabmate 0.4.0 with default feature server. Install: cargo install crabmate. Official Client pins default-features = false, features = ["protocol"] (crabmate::cm_sse_protocol, cm_types, … — not types/sse aliases). Until crates.io publish (S5), Client may still git-pin a rev.
• Semver surface: protocol = the six cm_* contract modules. server promises the composition module names (agent / config / llm / sse / types) and explicit root pub uses (run, run_agent_turn, build_tools*, …). #[doc(hidden)] modules and paths such as agent::agent_turn are not a stable SDK. Details: docs/design/crates_io_single_package.md §2.4.