Zero tool output tokens enter cloud context. In-process dispatch & 93.9% KV cache hit across 53 days of production telemetry.
1080p60 MP4
Quickstart
1. Install & Register (1 Command)
Universal Cloud-to-Local Agent Bridge & MCP Microkernel in Rust. Offload token-heavy code execution, testing, and file operations to any local LLM (Ollama, vLLM, LM Studio) at $0 cost.
2026-11-10
Sterne
—
Tools
—
Uptime
—
Register Castor automatically with all detected MCP clients (Claude Code, Claude Desktop, Antigravity IDE):
# Run directly via npx
npx -y mcp-castor install --client all
# Or install globally
npm install -g mcp-castor
castor install --client all
Or configure manually in your MCP client configuration (claude_desktop_config.json or mcp_config.json):
See the llama.cpp guide for managed startup/shutdown,
Windows and Linux examples, GGUF models, tool calling, and optional live tests.
Configuration persists in ~/.castor/config.json and respects CASTOR_* environment variable overrides.
System Architecture
Cloud coding agents (Claude Code, Gemini 3.8 Flash, Cursor) excel at system-level reasoning and planning, but reading thousands of lines of repository context or executing repetitive edit-and-test loops inflates cloud token costs and latency.
Castor provides an in-process Rust execution server as a Model Context Protocol (MCP) server. It splits work between cloud planning and local hands-on execution:
Developer
│
▼
Cloud Architect (Claude / Gemini / Antigravity)
│
│ MCP tool dispatch: castor_coworker(prompt, cwd)
▼
Castor Server (Local Rust Execution Server over stdio)
│
├─── 16 in-tree tools: read_file, write_file, edit_file, list_dir,
│ search_code, ast_search, ast_replace, git_status/diff/log/commit,
│ python_repl, paper_lookup, web_search, web_fetch, bash
│ └── Validated against sandbox boundaries & AST syntax gates
│
▼ Inference requests over HTTP (:18020)
Local Serving Engine (vLLM / Ollama / LM Studio)
│
▼ Grounded diffs & test results returned
Cloud Architect synthesizes final output
sequenceDiagram
autonumber
actor Dev as Developer
participant Cloud as Cloud Architect (Claude / Gemini)
participant Castor as Castor Server (Rust)
participant Local as Local Model (Ollama / vLLM / LM Studio)
Dev->>Cloud: High-level architectural task
Cloud->>Castor: castor_coworker(prompt, workspace)
activate Castor
loop In-Tree Autonomous Loop ($0 token cost)
Castor->>Local: Prompt + In-Tree Tool Definitions
Local-->>Castor: Tool Calls (ast_replace, bash, read_file)
Castor-->>Local: Tool Outputs + In-Memory AST Validation
end
Castor-->>Cloud: Grounded diffs & task deliverable
deactivate Castor
Cloud-->>Dev: Verified changes & synthesis
Key Principles
Zero Cloud Token Hoarding: The Lead Architect (cloud) directs tasks and reviews diffs without loading thousands of source lines into expensive prompt context.
In-Process Tool Dispatch Speed: Filesystem operations and structural AST mutations execute in-process (<0.1 ms dispatch) without subprocess spawning overhead.
Zero-Turn Reactive Wait: Long-running background jobs yield an OS-level wait hook (curl :18021/task/<id>/wait). Cloud supervisors block at $0 token cost and resume immediately upon task completion.
Sandboxed Workspace Confinement
Castor enforces a 5-layer defense-in-depth boundary ensuring neither coworker models nor external agents can escape the workspace root:
In-Memory Syntax Gate: Validates syntactical integrity (Rust, TypeScript, JavaScript, Python, JSON) before disk commits, rolling back automatically on errors.
Regression-tested against a 137-vector automated containment suite (123 attack vectors blocked, 14 allow vectors).
Consolidated MCP Interface
Castor registers three stdio tools across any MCP client:
Tool
Purpose
Primary Actions & Parameters
castor_coworker
Hands-on execution & peer programming
Dispatches a prompt to the sandboxed 16 builtin-tool runtime: read_file, write_file, edit_file, list_dir, search_code, ast_search, ast_replace, git_status, git_diff, git_log, git_commit, python_repl, paper_lookup, web_search, web_fetch, bash.
Actions: status, start, stop. Manages engine boots, health canaries, and auto-healing.
The 16 Built-in Coworker Tools
castor_coworker runs inside a sandboxed runtime exposing exactly these 16
in-tree tools (defined in src/tools/mod.rs):
Tool
Capability
read_file
Read source, PDFs (native in-memory extraction), and images for local visual inspection.
write_file
Create or overwrite a file (sandboxed to the workspace).
edit_file
Exact-substring, uniqueness-guarded edit with in-memory AST validation before commit.
list_dir
Directory listing with depth control.
search_code
Text/pattern search across the workspace.
ast_search
Structural AST search via native ast-grep.
ast_replace
Structural AST replace with automatic rollback on syntax error.
git_status
Short working-tree status.
git_diff
Staged or unstaged diff.
git_log
Recent commit history.
git_commit
Stage paths and commit.
python_repl
Stateful Python REPL scratchpad for computation and data analysis.
paper_lookup
Verified academic metadata via OpenAlex (titles, venues, DOIs, affiliations, OA PDFs).
web_search
Meta-search via SearXNG with Brave fallback.
web_fetch
Fetch and convert HTML/PDF/plain text to clean Markdown.
bash
Isolated shell with a 5-layer dangerous-command filter.
CLI Command Reference
# Model Context Protocol stdio server (default)
castor mcp
# Automatically register with MCP clients
castor install --client <all|claude|antigravity>
# Display operational telemetry dashboard
castor stats [-s 24h] [-d] [-j]
# Inspect effective configuration hierarchy
castor config
# Manage local inference engine lifecycle
castor server <status|start|stop>
# Clean stale sessions, leases, and tasks per retention policy
castor clean [--yes]
# Run zero-turn HTTP status and wait endpoint (:18021)
castor status
# Run universal SSE streaming proxy (:18022)
castor proxy
Operational Telemetry (castor stats)
Castor maintains an append-only JSONL event ledger in ~/.castor/sessions/*/events.jsonl. Running castor stats compiles a live terminal dashboard summarizing token efficiency and local execution metrics:
# View dashboard with full terminal formatting
castor stats
# Filter by time horizon (e.g., last 24 hours, 7 days)
castor stats -s 24h
# Output machine-readable JSON for monitoring
castor stats -j
Building from Source
# Prerequisites: Rust >= 1.85 (2024 edition)
git clone https://github.com/ApatheticMioz/Castor.git
cd Castor
# Build binary
cargo build --release
# Run the offline verification gate (unit + integration, deterministic mock/replay harnesses)
cargo test --all-features
# Register local release build with clients
./target/release/castor install --client all
Testing & Verification
Castor maintains a strict zero-warning and offline verification gate:
The live GPU tests (tests/llama_cpp.rs, tests/bonsai_deep_eval.rs) are
#[ignore]-gated and opt-in via ALLOW_ENGINE_INTERRUPT=1; they never run
in the default suite.
Universal Cloud-to-Local Agent Bridge & MCP Microkernel in Rust. Offload token-heavy code execution, testing, and file operations to any local LLM (Ollama, vLLM, LM Studio) at $0 cost.
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich MCP Castor?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt MCP Castor einen API-Schlüssel?
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Welchen Transport verwendet MCP Castor?
MCP Castor läuft lokal über stdio.
Wann wurde MCP Castor zuletzt geprüft?
Zuletzt geprüft: 2026-11-10. Universal Cloud-to-Local Agent Bridge & MCP Microkernel in Rust. Offload token-heavy code execution, testing, and file operations to any local LLM (Ollama, vLLM, LM Studio) at $0 cost.
