Warmplane

Security controls:

The local control plane that keeps Model Context Protocol (MCP) sessions warm with compact capability facades, policy governance, and deterministic execution.

v0.28.0 — Changelog · User Guide · Agent Skill · Performance · Whitepaper · OpenAPI

⚡ What is Warmplane?

Warmplane is a local control plane and reverse proxy for AI tool calling. It maintains persistent, warm connections to multiple upstream MCP servers and multiplexes them behind a single, governed interface.

The Problems Warmplane Solves

1. Context Window Token Bloat: Sending massive JSON schemas for dozens of tools on every turn wastes tens of thousands of prompt tokens. Warmplane provides a compact catalog index (cutting payload size by 58–96%), on-demand schema discovery, and SHA-256 ETag caching.
2. Poor Tool Descriptions & Ambiguity: Many upstream tools have sparse, misleading, or poorly phrased docstrings that confuse LLMs. Warmplane lets you override tool summaries and descriptions via polymorphic aliases (AliasTarget) and generates compact parameter signatures (tool(req, [opt])) to optimize zero-shot agent accuracy without upstream code edits.
3. Duplicate Invocations & Retries: When network hiccups occur, naive agents retry blind mutations. Warmplane provides crash-resilient, exactly-once idempotency deduplication (idk_<sha256>) and explicit retry classifications (safe, idempotent, unsafe).
4. Ungoverned Execution & Security: Connecting agents directly to live infrastructure risks unauthorized operations. Warmplane enforces multi-tenant RBAC, per-profile server constellations, secret redaction, and Human-in-the-Loop (HITL) approval gates.
5. Cascading Hangs & Flakiness: Slow or crashed upstream processes freeze agent loops. Warmplane monitors health with sub-microsecond circuit breakers and self-healing process supervision.

🚀 Quick Start

1. Installation

Homebrew (macOS & Linux):

brew tap warmplane/tap
brew install warmplane

Cargo (crates.io):

cargo install warmplane

# Optional: with local ONNX vector search (FastEmbed)
cargo install warmplane --features semantic-search

Build from Source:

git clone https://github.com/Warmplane/warmplane.git
cd warmplane
cargo install --path . --features semantic-search

2. Configure Upstream Servers

Add servers interactively or import from existing AI tools:

# Interactive setup wizard
warmplane server add

# Or non-interactively
warmplane server add filesystem --command npx --arg "-y" --arg "@modelcontextprotocol/server-filesystem" --arg "/tmp"
warmplane server add context7 --url "https://mcp.context7.ai/sse" --bearer-env "CONTEXT7_API_KEY"

# Or 1-click import from Claude Desktop, Cursor, OpenCode, Zed
warmplane config import

Or configure mcp_servers.json:

{
  "port": 9090,
  "toolTimeoutMs": 15000,
  "capabilityAliases": {
    "db.query": "sqlite.read_query",
    "search": {
      "target": "semble-rs.search",
      "summary": "Search codebase using semantic or BM25 ranking. Pass absolute repo path."
    }
  },
  "policy": {
    "allow": ["db.*", "fs.*", "search"],
    "deny": ["fs.delete*"],
    "requireApproval": ["db.mutation*"],
    "redactKeys": ["token", "password", "api_key"]
  },
  "profiles": {
    "coding": {
      "servers": ["filesystem", "sqlite"],
      "description": "Local engineering and exploration tools"
    }
  },
  "mcpServers": {
    "sqlite": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sqlite", "./test.db"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
  }
}

3. Connect or Start Warmplane

Choose the run-mode that matches your workflow:

• Mode 1: Direct MCP Stdio Integration (No background daemon needed): Point your AI client (Cursor, Claude Desktop, Antigravity) to warmplane mcp-server. The AI client spawns Warmplane directly as a child process:

  config.json

  Copy

  {
    "mcpServers": {
      "warmplane": {
        "command": "warmplane",
        "args": ["mcp-server", "--config", "mcp_servers.json", "--profile", "coding"]
      }
    }
  }
  

• Mode 2: Background Daemon & Web Control Deck: Run a central persistent daemon hosting the REST API, interactive Web UI, and audit logs:

  bash

  Copy

  warmplane daemon --port 9090
  

• Mode 3: Persistent Daemon with Streamable HTTP/SSE MCP Connection: If mcpHttpServer is configured, your AI clients can connect over HTTP/SSE (http://127.0.0.1:9191/sse) to a single shared daemon instance.

🔌 Client Interfaces

Warmplane exposes three primary access models sharing the same unified core state, policy gates, and telemetry:

1. Native MCP Stdio Proxy (warmplane mcp-server)

Point any MCP-native desktop client (Claude Desktop, Cursor, Zed, Windsurf) directly to Warmplane:

{
  "mcpServers": {
    "warmplane": {
      "command": "warmplane",
      "args": ["mcp-server", "--config", "mcp_servers.json", "--profile", "coding"]
    }
  }
}

2. HTTP REST Control Plane (warmplane daemon)

Full-featured HTTP JSON API for gateways, web apps, and backend services:

• GET /v1/capabilities: Compact capability catalog index
• POST /v1/capabilities/search: Hybrid lexical + semantic capability search
• POST /v1/tools/call: Normalized execution envelope with context distillation (_jsonpath, _limit_lines) and idempotency keys
• POST /v1/tools/batch_call: Chained multi-step execution with $step.field parameter interpolation
• GET /v1/tasks & POST /v1/tasks/:id/update: SEP-2663 async task lifecycle & HITL review
• GET /ui: Embedded standalone Web Control Deck

3. In-Process Embedded Engine (EmbeddedWarmplane)

Direct in-process Rust library for zero-overhead agent execution without HTTP child processes or network hops:

use warmplane::{EmbeddedWarmplane, engine::ExecutionOptions};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let (cp, _token) = EmbeddedWarmplane::start_from_path("mcp_servers.json").await?;
    let res = cp.call_capability(
        "filesystem.read_file",
        json!({ "path": "/tmp/test.txt" }),
        ExecutionOptions::default().with_request_id("req-1"),
    ).await;
    println!("Output: {:?}", res.data);
    Ok(())
}

🤖 Teach Your AI Agent Warmplane (Agent Skill)

Warmplane includes an official Agent Skill (.skills/warmplane/) adhering to the agentskills.io open standard. Point your coding agent (Claude Code, Google Antigravity, Cursor, OpenCode, Codex) directly to this repository:

# Install Warmplane Skill into Claude Code
claude skill install Warmplane/warmplane

# Or copy into your agent workspace
mkdir -p .agents/skills/warmplane && cp -r .skills/warmplane/* .agents/skills/warmplane/

• 📖 .skills/warmplane/SKILL.md — Core prompt triggers and standard agent workflows
• 🔌 references/mcp_stdio_usage.md — 1-Click client configs (17 IDEs) & MCP facade tools
• ⚙️ references/configuration_schema.md — mcp_servers.json schema & dynamic secrets
• 🛠️ references/cli_cheatsheet.md — Terminal commands for daemon, sync, and vault
• 🚑 references/error_resolution.md — Circuit breakers, policy denials, and recovery

📊 Performance Highlights

Warmplane is engineered in pure Rust with zero-cost abstractions:

• 50.4 ns: ETag Cache Validation (If-None-Match $\rightarrow$ 304 Not Modified)
• 159.8 ns: Idempotent Cache-Hit Deduplication
• 1.58 µs: SHA-256 Incremental Catalog Version Hashing ($N=10$)
• 15.9 µs: Filtered Hybrid Capability Search ($N=50$)
• 372.1 µs: Zero-Allocation Lexical Tag Search across 1,000 Tools

👉 See complete benchmarks and methodology in docs/PERFORMANCE.md.

🛡️ Core Capabilities Matrix