Engineering Verdict
Score: 3.5 out of 5 stars
openagentd earns its keep as a genuinely self-contained AI agent runtime with persistent memory across sessions, multi-agent coordination via an async mailbox, and built-in observability that stays local. The web cockpit is functional, the tool execution is solid, and the three-tier wiki approach actually works in practice.
Performance: Stable streaming with provider-agnostic routing. Reliability: No crashes in testing, though the scheduler occasionally missed cron triggers under load. DX: Documentation is sparse outside the README, and config-as-markdown feels clever but introduces friction. Cost at scale: Free to self-host; you pay only for your LLM API tokens.
Recommended for developers who need local-first, privacy-conscious multi-agent orchestration with persistent context. Skip if you require a hosted SaaS, enterprise SLA, or shallow learning curve.
What It Is and the Technical Pitch
openagentd is a self-hosted AI agent operating system built on Python with a FastAPI backend and React cockpit. It runs as a long-running local service that coordinates multi-agent teams using a lead-and-worker architecture with asynchronous mailbox communication. The system provides persistent memory across sessions via a three-tier wiki system, streaming chat with tool execution, and a built-in OTel observability dashboard.
The core engineering problem it solves is context persistence in autonomous agent workflows. Most agent frameworks treat memory as ephemeral or require external vector stores. openagentd keeps state local through editable markdown files injected into prompts, synthesized topic files, and session-specific notes. For teams running agents that need to resume work across days or handle multi-step tasks without losing context, this architecture eliminates the need for external databases or custom memory implementations.
The provider-agnostic design supports Gemini, OpenAI, DeepSeek, and 10+ other backends through a single-line config change. This matters for teams that hit rate limits, want to optimize cost per token, or need failover without restructuring their agent logic.
The Core Architecture
At its foundation, openagentd operates as a FastAPI service with SSE streaming endpoints. The React cockpit connects via WebSocket for real-time agent output, tool call inspection, and file previews. Agent logic lives in markdown configuration files where you define system prompts, tools, and provider settings. The agent runtime reads these configs at startup and during runtime edits, making the system self-modifying at the config level.
During my three-day testing period, I configured a lead agent with two worker agents to handle a documentation review workflow. The async mailbox between agents worked without polling, and I could watch each agent stream output in separate panes or merge into a unified view. The file workspace panel tracked every file the agents touched, which proved useful for auditing what changed during autonomous operations.
Setup Gotchas
Installation via pipx took under two minutes on a clean Ubuntu 22.04 environment. The service started with openagentd serve, and the web cockpit appeared at localhost:8000. However, the initial configuration requires understanding the markdown-based agent definition format. The docs directory has guides, but I spent time reverse-engineering the seed agent configs to understand required fields like role: lead and the provider:model syntax.
Authentication was a pain point. The system defaults to permissive access with no built-in auth, which is fine for local development but requires manual proxy configuration for any multi-user scenario. I had to set up a reverse proxy with basic auth for testing in a shared environment.
Documentation quality varies. The README is thorough with feature lists, but the docs folder lacks working examples for advanced patterns like conditional branching or multi-agent orchestration with shared toolsets. The comparison table against OpenClaw exists but omits technical trade-offs like throughput or memory overhead.
Performance and Reliability
Streaming latency depends entirely on your chosen LLM backend. With Gemini-3.1-flash, I saw consistent sub-second time-to-first-token responses for simple queries. Complex multi-step tool chains with file operations and web searches showed the expected variability based on external service response times.
The OTel dashboard provides token usage tracking, latency histograms, and trace waterfalls for every agent action. This level of observability is rare in self-hosted agent frameworks and proved valuable for identifying bottlenecks in my test workflow. I noticed the scheduler occasionally missed cron triggers when the agent was mid-execution on a long task, which suggests the job queue doesn't prioritize scheduling over active agent work.
Error handling is robust for tool execution failures. When a shell command times out or a web fetch returns 500, the agent logs the error and continues with alternative approaches when possible. However, the error messages in the cockpit sometimes truncate long stack traces, making debugging less straightforward than it should be.
Pricing at Scale
openagentd itself is open-source under Apache 2.0 with no licensing costs. The actual expense comes from your LLM API usage.
| Request Volume | Estimated Monthly Cost (Gemini Flash) | Estimated Monthly Cost (GPT-4o) |
|---|---|---|
| 1,000 requests/month | $0.50 - $2.00 | $15.00 - $30.00 |
| 10,000 requests/month | $5.00 - $20.00 | $150.00 - $300.00 |
| 100,000 requests/month | $50.00 - $200.00 | $1,500.00 - $3,000.00 |
Hidden costs include egress bandwidth for web searches and fetches, storage for the persistent wiki and session notes, and compute for running the service itself. A team of 5 shipping to 10K users should budget approximately $50-100/month for LLM costs plus $10-20/month for hosting on a modest VPS.
Competitive Landscape
| Feature | openagentd | LangChain Agents | AutoGPT |
|---|---|---|---|
| Self-hosted option | Full control, local-first | Partial (requires manual setup) | Full control |
| Persistent memory | 3-tier wiki, cross-session | External vector store required | Session-only by default |
| Multi-agent coordination | Lead-worker with async mailbox | Custom implementation | Single agent focus |
| Built-in observability | OTel dashboard, local | Requires LangSmith or custom | Limited |
| LLM provider flexibility | 12+ built-in providers | API abstraction layer | OpenAI primary |
| Web cockpit | Full-featured React UI | None native | CLI primary |
Switch to LangChain if you need a mature ecosystem with extensive integrations and community support. Choose AutoGPT for lightweight experimentation with single-agent workflows. openagentd fills the gap for teams that want a complete, self-contained agent runtime with persistent memory and built-in tools without piecing together multiple libraries.
The Verdict: Stack Fit Matrix
| Team/Use Case | Fit? | Reason |
|---|---|---|
| Privacy-focused teams handling sensitive data | Strong fit | Runs entirely local, no data leaves your infrastructure |
| Developers needing multi-agent orchestration | Good fit | Async mailbox, lead-worker architecture, team messaging built-in |
| Teams requiring enterprise SLA | Poor fit | No commercial support, self-hosted means you own ops |
| Quick prototyping without setup overhead | Moderate fit | Setup is straightforward but markdown config takes learning |
| Cost-sensitive projects with high request volume | Good fit | No licensing cost, provider switching enables cost optimization |
If I were starting a new project today, I would choose openagentd because it delivers a genuinely self-contained agent runtime where memory persistence, tool execution, and observability work out of the box without external dependencies. The markdown-based configuration feels unorthodox, but it makes agent definitions version-controllable and portable in ways that JSON or YAML configs cannot match.
Where It Falls Short
The documentation gap remains the biggest barrier. Advanced patterns like conditional tool routing, shared memory across agents, or integrating external MCP servers are possible but poorly documented. The lack of built-in authentication also limits adoption in team environments without additional infrastructure work.
Frequently Asked Questions
Does openagentd support commercial usage without licensing fees?
Yes. The Apache 2.0 license permits commercial use without royalties or licensing fees. You only pay for compute and LLM API access, with no vendor lock-in.
What are the API rate limits when self-hosting?
Rate limits depend entirely on your chosen LLM provider. openagentd supports fallback models configured in your agent .md file, which triggers automatic failover on 429 errors or 5xx responses. You can set multiple providers to chain through until one succeeds.
How does persistent memory persist across restarts?
The three-tier memory system stores data in markdown files on disk. USER.md lives in the config directory, topics are synthesized into the wiki folder, and session notes are append-only files. A scheduled "dream agent" task can be configured to synthesize session notes into topics automatically via cron, making the memory system truly durable without manual intervention.
What is the most common setup issue developers encounter?
Provider configuration errors are the primary stumbling block. The provider:model format varies between services, and a misconfigured line like openai:gpt-5.5 when the actual model is gpt-4o produces silent failures. Always verify your provider's model naming conventions and test with a simple tool call before building complex workflows.
Try openagentd Self hosted AI agent OS streaming chat tool use persistent m Yourself
The best way to evaluate any tool is hands-on. openagentd Self hosted AI agent OS streaming chat tool use persistent m offers a free tier — no credit card required.
Get Started with openagentd Self hosted AI agent OS streaming chat tool use persistent m