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
Yıldızlar
—
Araçlar
—
Çalışma süresi
—
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.
Henüz araç listesi yok. Uzak sunucular ilk sağlık kontrolünden sonra bir liste alır.
SSS
Sorular
MCP Castor nasıl kurulur?
Bu sayfadan Cursor, Claude Desktop, Claude Code veya VS Code için stdio yapılandırmasını kopyalayın. PlugMCP proxy'sini değil, yayıncının kurulumunu kullanır.
MCP Castor için API anahtarı gerekiyor mu?
Bu kayıtta gerekli bir ortam değişkeni listelenmiyor.
MCP Castor hangi aktarımı kullanıyor?
MCP Castor yerel olarak stdio üzerinden çalışır.
MCP Castor en son ne zaman kontrol edildi?
Son kontrol: 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.
