A self-hosted autonomous agent that runs inside a Firecracker microVM — so it can plan, write code, and call tools without ever touching your host filesystem, your LLM credentials, or your API secrets.
strangeClaw is a small autonomous agent built from scratch (no agent framework) as a way for me to understand how these systems actually work — and then to try a security idea that seemed worth exploring: what if the agent runs behind a real VM boundary, and credentials never enter the environment it controls?
In Fire mode, the agent loop runs inside a Firecracker microVM with no host filesystem access and no secrets. When it needs an authenticated API call, the request goes to a host-side broker that checks policy, injects credentials, redacts the response, and hands back only the result. The agent observes denials instead of holding keys. Risky work stays inside the VM.
Status: Work in progress, not production-ready. It's a personal project, but a working one — Yolo mode, Fire mode, the request broker, and optional sequential subagents all run today.
Next up: parallel subagents.
Why This Exists
The project is a way for me to learn by building. I wanted to build my own agent loop instead of using an agent framework, then use that as a base to try security ideas that seemed worth exploring.
The main security experiment is running the agent inside a Firecracker microVM, so commands and tools run behind a VM boundary instead of directly on the host. The request broker is another part of that: keep API credentials on the host, inject them only when a request passes policy, and let the agent observe denials instead of giving it direct access to secrets.
How it works
A strict agent loop — Inspect → Choose → Act → Observe → Repeat — that runs until the model finishes, asks for clarification, or replans. Two execution modes:
yolo— direct host execution for trusted local workflows.fire— Firecracker microVM isolation with host-side credential brokering.
Architecture
HOST
┌────────────────────────────────────────────────────────────────┐
│ User / Adapter / Coordinator │
│ │
│ Host secrets.yaml ──► Request Broker ──► External APIs │
│ policy check │
│ credential injection │
│ response redaction │
│ │
│ SANDBOX │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Agent loop │ │
│ │ Inspect → Choose → Act → Observe → Repeat │ │
│ │ │ │
│ │ Tools + skills context │ │
│ │ │ │
│ │ In Fire mode: no host filesystem, no API secrets, │ │
│ │ no LLM credentials. Risky work stays inside the VM. │ │
│ └────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
What It Supports
- A strict agentic loop: Inspect -> Choose -> Act -> Observe -> Repeat.
- Two execution modes:
yolo: direct host execution for trusted local workflows.fire: Firecracker microVM isolation.
- CLI and Telegram adapters.
- Provider-agnostic LLM access through LiteLLM.
- Host-side LLM proxy in Fire mode, so LLM credentials stay off the guest.
- Host-side request broker for
web_search,web_fetch, andhttp_request. - Skills loaded from
skills/<name>/SKILL.mdusing the Agent Skills format. - Optional sequential subagents: the agent can delegate a subtask to a child agent in the same sandbox (disabled by default).
- Per-session state, output files, optional event journals, and Fire runtime log export.
Subagents
The agent can delegate a separable subtask to a child agent that runs in the same sandbox and returns a single result. Subagents are disabled by default and gated by two switches that must both be true:
tools: spawn_subagent: false # the model can see the capability subagents: enabled: false # the runtime will run a child
Children run sequentially (one at a time, in the parent's thread), use only a subset of the parent's tools, cannot recurse, and cannot ask the user. In this release they help with context economy and focus, not speed — a child does noisy work in its own context and hands back a compact result, so the parent can take on larger tasks without its own context collapsing. Parallel subagents (the actual speedup) are future work. See Architecture and Configuration.
Quick Start
For a local trusted run:
python3 -m venv .venv .venv/bin/pip install -e ".[dev]" mkdir -p ~/.strangeclaw cp config.example.yaml ~/.strangeclaw/config.yaml .venv/bin/python -m main
Set mode: yolo and your llm settings in
~/.strangeclaw/config.yaml. See Setup for the full
walkthrough.
Documentation
- Setup: install, configure, and run Yolo or Fire mode.
- Architecture: runtime model, agent loop, tools, skills, sessions, and security boundaries.
- Configuration: LLMs, web search, secrets, integrations, Telegram, and adapters.
- Fire Mode: Firecracker-specific behavior, troubleshooting, host services, credential isolation, and cleanup.
Current Limitations
- Fire mode requires Linux with KVM plus elevated privileges for TAP and iptables management.
- Fire rootfs images must be rebuilt when guest code, built-in skills, or guest dependencies change.
- Fire mode does not support resume across sessions; files persist only while a session VM is running.
shellis powerful and high risk. Use Yolo mode only for trusted workflows, and review tool settings before running untrusted tasks.- The project is intended for local experimentation, not production deployment or multi-user SaaS.
Future Work
- Expand the built-in skill set, especially for coding workflows, research, and personal knowledge work.
- Add more integration-focused skills and broker policy examples for common APIs.
- Improve custom skill delivery in Fire mode without rebuilding the rootfs.
- Add more adapters and better observability for session replay and debugging.
- Parallel subagents, building on the current sequential foundation.
License
strangeClaw is licensed under the MIT License. If you find the idea useful, feel free to use it, take it apart, change it, and build on it. See LICENSE.