HybridClaw Documentation
Runtime Architecture & Design Principles
A lightweight open-source agent runtime — built for performance, security, scaling and resilience.
Design Principles
Six principles guide the HybridClaw runtime. Each principle is reflected in concrete code, not just marketing copy.
Lightweight by default
Single Go-style binary, no cluster, no Kubernetes required to start. Boots in under a second on a laptop. Production deployments can scale to N workers but never need them to begin.
Local-first execution
Agents run where the data lives. Skills, tool calls and browser automation execute in the user's environment by default — no plaintext data leaves the perimeter unless explicitly routed via the control plane.
Deterministic skills
Skills are versioned, content-addressed manifests. The same input + same skill version = the same trajectory. Makes evals meaningful and rollbacks safe.
Sandboxed tool use
Every tool runs in an isolated execution context with explicit capability grants. Browser automation, file access, shell commands — all gated by signed manifests and runtime policy.
Content-addressed artifacts
Trajectories, skill outputs and audit records are content-addressed. This makes traces reproducible, replayable and tamper-evident — a prerequisite for compliance.
Observable everything
Every span, every tool call, every model invocation emits structured telemetry by default. Operators get monitoring dashboards and KPIs out of the box, not as an afterthought.
Performance & Scaling
HybridClaw scales from a single laptop to fleets of workers without changing the agent code. The same skill manifest runs on a developer's machine and a production cluster — the runtime handles the difference.
-
Agent-level concurrency. Each agent has its own task queue. Long-running tool calls do not block sibling agents.
-
Batched LLM calls. Multiple in-flight prompts to the same model are coalesced when possible — cuts cost and latency for high-volume workloads.
-
Multi-layer cache. Skill outputs, retrieval results and tool responses are cached at three levels: in-memory, on-disk, and shared across workers when explicitly opted in.
-
Worker scaling. Scale horizontally by adding worker processes. Coordination via the HybridAI control plane (queue + leader election) when multi-node — no shared mutable state in the runtime itself.
-
Streaming everywhere. Model outputs, tool results and channel responses stream end-to-end. No waiting for full completion before downstream steps start.
Security
Agent platforms multiply the blast radius of every security mistake. HybridClaw assumes hostile inputs and constrains what an agent can do — even if a model is jailbroken or a prompt is poisoned.
Secrets vault
Tools never see raw credentials. Secrets are referenced by ID and resolved at runtime through the control plane.
RBAC & capability grants
Per-agent, per-skill, per-tool permissions. Default-deny.
Sandboxed execution
File access, shell commands and browser automation run in isolated contexts with no host-network access by default.
Signed skill manifests
Skills are verified against signed manifests before execution. No unsigned code paths in production.
Human-in-the-loop gates
High-impact actions (transfers, deletes, external mails) can require human approval — configurable per skill, audit-logged.
Tamper-evident audit log
Every action is content-addressed and chained. Operators can prove what an agent did, when, and on whose authority.
Resilience
Production agents fail. Models time out, tools return errors, networks partition. HybridClaw treats failure as the default case, not an edge case.
| Failure Mode | Runtime Behavior |
|---|---|
| Transient model error | Exponential backoff; falls back to a configured alternate model on repeat failure. |
| Tool exception | Error captured in the trajectory; agent can retry, choose a different tool, or escalate. |
| Worker crash | Task is requeued; idempotent skills can resume from last checkpoint. Non-idempotent skills surface a manual replay decision. |
| Bad skill version | Eval gate blocks deploy if regression score crosses threshold. If it slips through, rollback is one command and content-addressed. |
| Dead-letter queue | Tasks that exceed retry budget land in a DLQ for human inspection — never silently dropped. |
| Cost runaway | Per-agent budgets cap spend. Soft limits warn; hard limits stop new tasks until lifted. |
Self-Hosted Runtime · Managed Control Plane
HybridClaw is the open-source runtime. HybridAI is the EU-hosted control plane. You can run them together (managed cloud), apart (self-hosted runtime + managed control plane), or fully self-hosted.
HybridClaw Runtime (Open Source)
- • Agent execution + skill manifests
- • Tool sandboxing & browser automation
- • Local trajectory + telemetry collection
- • Multi-channel adapters (Discord, Teams, WhatsApp, Email, Web, Terminal)
HybridAI Control Plane (Managed)
- • RAG, memory, company knowledge
- • RBAC, secrets vault, audit log
- • Observability dashboards & KPIs
- • Skill evals, scorecards, deploy gates
- • Budgets & cost routing
- • EU hosting, GDPR & AI-Act compliant