Project Overview
Source Files
This page is generated from the following source files:
OpenFang is an open-source Agent Operating System written in Rust that enables autonomous agents to work independently on schedules, 24/7. Unlike traditional agent frameworks that wait for user input, OpenFang agents proactively build knowledge graphs, monitor targets, generate leads, manage social media, and report results without manual prompting. The entire system compiles to a single ~32MB binary with zero external runtime dependencies, enabling deployment with a single install command (README.md:40-49).
The project's core innovation is Hands — pre-built autonomous capability packages that run independently on schedules. Each Hand bundles a manifest (HAND.toml), multi-phase operational system prompts (500+ word expert procedures), domain expertise references (SKILL.md), and guardrails with approval gates for sensitive actions. This architecture transforms agents from reactive chatbots into proactive workers that execute complex workflows autonomously (README.md:64-76).
Technically, OpenFang is a 14-crate Rust workspace targeting Rust 1.75+, with configuration stored at ~/.openfang/config.toml and the default API exposed at http://127.0.0.1:4200. The compiled CLI binary (target/release/openfang.exe or target/debug/openfang.exe) serves as the primary interface for daemon management, agent lifecycle, and system operations (CLAUDE.md:1-8).
Architecture Module Structure
OpenFang implements a modular 14-crate workspace architecture with clear separation of concerns across distinct functional domains. The workspace definition in Cargo.toml:1-26 enumerates all crate members: openfang-types, openfang-memory, openfang-runtime, openfang-wire, openfang-api, openfang-kernel, openfang-cli, openfang-channels, openfang-migrate, openfang-skills, openfang-hands, openfang-extensions, openfang-desktop, and xtask.
正在加载图表渲染器...
The architecture diagram above illustrates the layered dependency structure. The Core Layer provides foundational capabilities: shared type definitions (openfang-types), SQLite-backed memory with vector embeddings (openfang-memory), and the execution runtime with WASM sandboxing (openfang-runtime). The Service Layer orchestrates agent lifecycle (openfang-kernel), exposes 100+ API endpoints via Axum 0.8 (openfang-api), and handles peer-to-peer communication with HMAC-SHA256 authentication (openfang-wire). The Interface Layer encompasses the CLI with 14+ subcommands, 40+ channel adapters (Telegram, Discord, Slack, etc.), and the desktop application. The Extension Layer supports WASM-based skills, autonomous Hands packages, and a plugin system.
The dependency selection in Cargo.toml:27-90 reveals key architectural decisions: Tokio for async runtime, Axum 0.8 with WebSocket support for the HTTP server, Wasmtime 41 for WASM sandboxing, and rusqlite for the embedded database. Security dependencies include Ed25519-Dalek for signed manifests, AES-GCM for encryption, and Argon2 for key derivation. The changelog confirms this architecture supports agent lifecycle management, structured KV memory with semantic recall, and 41 built-in tools (CHANGELOG.md:12-22).
Core Module Deep Dive
| Module | Responsibility | Key Dependencies |
|---|---|---|
openfang-types | Shared type definitions, error types, domain models | serde, thiserror, uuid |
openfang-memory | SQLite storage, vector embeddings, semantic recall | rusqlite, chrono |
openfang-runtime | WASM sandbox, tool execution, TTS/MCP/A2A protocols | wasmtime, tokio, reqwest |
openfang-kernel | Agent lifecycle, workflow engine, trigger system | All core modules |
openfang-api | REST/WS/SSE endpoints, OpenAI-compatible API | axum, tower-http |
openfang-channels | 40+ messaging adapters with unified bridge | tokio-tungstenite, lettre |
Key Features Capabilities
OpenFang provides a comprehensive feature set spanning autonomous execution, LLM integration, security, and multi-channel communication. The core platform offers 41 built-in tools covering filesystem operations, web requests, shell execution, browser automation, scheduling, collaboration, image analysis, inter-agent communication, TTS synthesis, and media handling. The WASM sandbox implements dual metering with fuel consumption and epoch interruption via a watchdog thread, ensuring untrusted code cannot compromise system stability (CHANGELOG.md:14-22).
The workflow engine supports pipelines, fan-out parallelism, conditional steps, loops, and variable expansion. A visual workflow builder provides drag-and-drop node graph editing with 7 node types and TOML export capability. The trigger system implements event pattern matching, content filters, and fire limits. Seven bundled Hands packages deliver autonomous agent actions out-of-the-box (README.md:78-80).
LLM Support Matrix
The LLM integration layer provides 3 native drivers (Anthropic, Google Gemini, OpenAI-compatible) with support for 27 providers including Anthropic, Gemini, OpenAI, Groq, OpenRouter, DeepSeek, Together, Mistral, Fireworks, Cohere, Perplexity, xAI, AI21, Cerebras, SambaNova, Hugging Face, Replicate, Ollama, vLLM, and LM Studio. The model catalog contains 130+ built-in models with 23 aliases and tier classification. Intelligent model routing uses task complexity scoring, and a fallback driver provides automatic failover between providers. All drivers support streaming via Server-Sent Events (SSE) (CHANGELOG.md:24-31).
正在加载图表渲染器...
The sequence diagram above illustrates the request flow from user input through the API layer, kernel orchestration, runtime tool execution, LLM completion streaming, and memory persistence. The API layer accepts requests via REST or WebSocket, routes them to the appropriate agent through the kernel, which loads conversation context from the memory substrate. The runtime executes any required tools, streams completions from the LLM provider, stores results in memory, and returns the formatted response.
Security Architecture
Security features include capability-based access control with privilege escalation prevention, path traversal protection in all file tools, and SSRF protection blocking private IPs and cloud metadata endpoints. Agent manifests are signed with Ed25519, and a Merkle hash chain provides tamper-detection audit trails. The peer wire protocol uses HMAC-SHA256 mutual authentication. API key authentication supports Bearer tokens with GCRA rate limiting using cost-aware token buckets. All API key fields implement secret zeroization, and subprocess environments are isolated. The loop guard uses SHA256-based detection with circuit breaker thresholds (CHANGELOG.md:41-56).
Development Quality Assurance
The project enforces a strict build workflow after every feature implementation: workspace compilation (cargo build --workspace --lib), full test suite execution (cargo test --workspace with 1,744+ tests), and Clippy linting with zero warnings (cargo clippy --workspace --all-targets -- -D warnings). This tripartite verification ensures code quality, test coverage, and lint compliance before any merge (CLAUDE.md:9-15).
Mandatory live integration testing complements unit tests to catch issues that compile successfully but fail at runtime: missing route registrations in server.rs, config fields not deserialized from TOML, type mismatches between kernel and API layers, and endpoints returning wrong or empty data. The development commands in README.md:445-459 document the standard workflow for building, testing, linting, and formatting.
Release Profile Configuration
The release profile in Cargo.toml:151-162 enables Link-Time Optimization (LTO), single codegen unit, symbol stripping, and optimization level 3 for maximum performance and minimal binary size. An alternative release-fast profile inherits from release but uses thin LTO, 8 codegen units, optimization level 2, and no symbol stripping for faster build times during development iteration.
toml1# Release profile for production binaries 2[profile.release] 3lto = true # Full link-time optimization 4codegen-units = 1 # Single codegen unit for better optimization 5strip = true # Strip symbols for smaller binary 6opt-level = 3 # Maximum optimization 7 8# Fast release profile for development 9[profile.release-fast] 10inherits = "release" 11lto = "thin" # Faster LTO 12codegen-units = 8 # Parallel codegen 13opt-level = 2 # Balanced optimization 14strip = false # Keep symbols for debugging
Multi-Language Project Detection
The runtime module implements automatic project type detection to provide context-aware assistance across polyglot development environments. The detect_project_type function in crates/openfang-runtime/src/workspace_context.rs:178-202 checks for characteristic files to identify the project type:
| Project Type | Detection Files |
|---|---|
| Rust | Cargo.toml |
| Node.js | package.json |
| Python | pyproject.toml, setup.py, requirements.txt |
| Go | go.mod |
| Java | pom.xml, build.gradle |
| .NET | *.csproj, *.sln |
The detection logic uses filesystem existence checks for most project types, with a special has_extension_in_dir helper function for glob-style patterns (.csproj, .sln) that don't work with standard exists() calls. When no characteristic files are found, the function returns ProjectType::Unknown.
Unit tests in crates/openfang-runtime/src/workspace_context.rs:263-309 validate detection for each project type by creating temporary directories with the appropriate marker files, asserting correct detection, and cleaning up afterward. This test coverage ensures reliable project type identification across supported languages.
Technical Stack Summary
| Category | Technology | Version | Purpose |
|---|---|---|---|
| Language | Rust | 1.75+ | Primary implementation language |
| Async Runtime | Tokio | 1.x | Async I/O and task scheduling |
| HTTP Server | Axum | 0.8 | REST/WebSocket/SSE endpoints |
| Database | rusqlite | 0.31 | Embedded SQLite storage |
| WASM Runtime | Wasmtime | 41 | Skill sandboxing |
| Serialization | serde, serde_json | 1.x | JSON/TOML/MessagePack |
| HTTP Client | reqwest | 0.12 | LLM API calls |
| WebSocket | tokio-tungstenite | 0.24 | Channel adapters |
| CLI | clap | 4.x | Command-line interface |
| TUI | ratatui | 0.29 | Interactive terminal UI |
| Crypto | ed25519-dalek, aes-gcm | 2.x, 0.10 | Signatures, encryption |
Quantitative Capabilities
The OpenFang platform delivers substantial capabilities across multiple dimensions:
- 14 crates in the Rust workspace providing modular architecture
- 41 built-in tools for agent capabilities
- 130+ LLM models in the catalog with 23 aliases
- 27 LLM providers supported through 3 native drivers
- 40+ channel adapters for multi-platform communication
- 100+ API endpoints (REST/WS/SSE)
- 1,744+ unit tests ensuring code quality
- 7 bundled Hands for autonomous operations
- ~32MB single binary deployment footprint
Report Reading Roadmap
正在加载图表渲染器...
The roadmap above illustrates the recommended reading sequence. After completing this overview, readers should explore the Architecture & Module Structure section for detailed component interactions, followed by Key Features & Capabilities for functional understanding. Security Implementation, API Design, Channel Adapters, and Hands documentation provide specialized deep dives for specific integration scenarios.