relayplane

# RelayPlane **OpenRouter routes. RelayPlane observes, governs, and learns.** Agent ops for OpenClaw power users. Your agents make hundreds of API calls per session — RelayPlane gives you visibility, cost control, and governance over all of them. ## What It Does RelayPlane is an **optional optimization layer** that sits in your agent's request pipeline. It routes simple tasks to cheaper models, enforces budgets, and logs everything — with automatic fallback to direct provider calls if anything goes wrong. **Key principle: RelayPlane is never a dependency.** If the proxy dies, your agents keep working. Zero downtime, guaranteed. ## Installation ```bash npm install -g @relayplane/proxy@latest ``` ## Quick Start ```bash # 1. Start the proxy (runs on localhost:4100 by default) relayplane-proxy # 2. Add to your openclaw.json: # { "relayplane": { "enabled": true } } # 3. That's it. OpenClaw routes through RelayPlane when healthy, # falls back to direct provider calls automatically. ``` ## ⚠️ Important: Do NOT Set BASE_URL **Never do this:** ```bash # ❌ WRONG — hijacks ALL traffic, breaks OpenClaw if proxy dies export ANTHROPIC_BASE_URL=http://localhost:4100 ``` **Instead, use the config approach:** ```json // ✅ RIGHT — openclaw.json { "relayplane": { "enabled": true } } ``` The config approach uses a circuit breaker — if the proxy is down, traffic goes direct. The `BASE_URL` approach has no fallback and will take down your entire system. ## Architecture ``` Agent → OpenClaw Gateway → Circuit Breaker → RelayPlane Proxy → Provider ↓ (on failure) Direct to Provider ``` - **Circuit breaker:** 3 consecutive failures → proxy bypassed for 30s - **Auto-recovery:** Health probes detect when proxy comes back - **Process management:** Gateway can spawn/manage the proxy automatically ## Configuration Minimal (everything else has defaults): ```json { "relayplane": { "enabled": true } } ``` Full options: ```json { "relayplane": { "enabled": true, "proxyUrl": "http://127.0.0.1:4100", "autoStart": true, "circuitBreaker": { "failureThreshold": 3, "resetTimeoutMs": 30000, "requestTimeoutMs": 3000 } } } ``` ## Commands | Command | Description | |---------|-------------| | `relayplane-proxy` | Start the proxy server | | `relayplane-proxy stats` | View usage and cost breakdown | | `relayplane-proxy --port 8080` | Custom port | | `relayplane-proxy --offline` | No telemetry | | `relayplane-proxy --help` | Show all options | ## Programmatic Usage (v1.3.0+) ```typescript import { RelayPlaneMiddleware, resolveConfig } from '@relayplane/proxy'; const config = resolveConfig({ enabled: true }); const middleware = new RelayPlaneMiddleware(config); // Route a request — tries proxy, falls back to direct const response = await middleware.route(request, directSend); // Check status const status = middleware.getStatus(); console.log(middleware.formatStatus()); ``` ### Advanced: Full Agent Ops Proxy ```typescript import { createSandboxedProxyServer } from '@relayplane/proxy'; const { server, middleware } = createSandboxedProxyServer({ enableLearning: true, // Enable pattern detection enforcePolicies: true, // Enforce budget/model policies relayplane: { enabled: true }, // Circuit breaker wrapping }); await server.start(); // All three pillars active: Observes + Governs + Learns // Circuit breaker protects against proxy failures ``` ## What's New in v1.4.0 **Three Pillars — All Integrated:** - **Observes** (Learning Ledger) — every run captured, full decision explainability - **Governs** (Policy Engine) — budget caps, model allowlists, approval gates - **Learns** (Learning Engine) — pattern detection, cost suggestions, rule management **Sandbox Architecture (v1.3.0+):** - **Circuit breaker** — automatic failover, no more system outages - **Process manager** — proxy runs as managed child process - **Health probes** — active recovery detection - **Stats & observability** — p50/p95/p99 latencies, request counts, circuit state **Learning Engine Endpoints (v1.4.0):** - `GET /v1/analytics/summary` — analytics with date range - `POST /v1/analytics/analyze` — detect patterns, anomalies, generate suggestions - `GET /v1/suggestions` — list pending suggestions - `POST /v1/suggestions/:id/approve` / `reject` — suggestion workflow - `GET /v1/rules` — active rules - `GET /v1/rules/:id/effectiveness` — is this rule helping? ## Privacy - **Your prompts stay local** — never sent to RelayPlane servers - **Anonymous telemetry** — only token counts, latency, model used - **Opt-out anytime** — `relayplane-proxy telemetry off` - **Fully offline mode** — `relayplane-proxy --offline` ## Links - **Docs:** https://relayplane.com/docs - **GitHub:** https://github.com/RelayPlane/proxy - **npm:** https://www.npmjs.com/package/@relayplane/proxy