OpenFang

Whitepaper

Architecture Layers & 16-Layer Security

Overview
What It Is
Core Concepts
Architecture
Security (16 Layers)
Hands
Ecosystem
Getting Started
Benchmarks
Whitepaper
Sources

Architecture and Security Technical Whitepaper

Version: v0.1
Date: 2026-02-26

Note: This document is a technical whitepaper summarizing the architecture and security design based on official OpenFang documentation and public repositories.

Abstract

OpenFang treats "Intelligent Agents" as long-running system entities rather than just one-off conversational interactions. Its core is written in Rust and layered around a Kernel orchestrator, Runtime execution, Memory persistence, and external interfaces (API/Channels/Wire). It implements a 16-layer defense-in-depth security system managing capability authorization, sandbox isolation, audit chains, information flow control, supply chain integrity, network access protection, secret zeroization, and rate limiting against critical risk vectors.

1. Background and Objectives

1.1 Why Do We Need an "Agent OS"?

Traditional Agent Frameworks act primarily like "libraries": combining prompts, tool calls, and workflow orchestration to accomplish a single task. An Agent OS addresses long-running systemic issues: lifecycle hosting, isolation, governance, upgrading, auditing, quotas, and cost tracking.

1.2 Scope of the Whitepaper

This document focuses on:

  • Architectonics: crate stratification, kernel boot sequence, agent lifecycles, and core subsystems.
  • Security Architecture: The threat modeling and implementation highlights of its 16 independent security systems.

It does not cover: In-depth API references, granular details of every Hand/Skill, or reproducible performance benchmarks.

2. Overall Architectural Overview

2.1 Cargo Workspace and Stratification

According to the official Architecture document, OpenFang is organized as a Cargo workspace with 14 crates (13 code + xtask), strictly adopting a top-down dependency design with no circular references.

Key Layers (Simplified):

  • openfang-types: Shared types, capability models, taint tracking, manifest signing, etc.
  • openfang-memory: SQLite memory substrate (including sessions, vector search, usage, canonical sessions).
  • openfang-runtime: Agent loops, LLM drivers, tools, WASM sandboxing, audit chains.
  • openfang-kernel: The assembly and orchestration hub (scheduling, RBAC, workflows, metering).
  • openfang-api: HTTP/WS/SSE interfaces and middleware security.
  • openfang-channels: 40+ channel adapters and connection policies.
  • openfang-wire (OFP): Peer-to-peer communication and mutual authentication.

2.2 Kernel Boot Sequence

According to the Architecture docs, the Kernel executes the following during boot_with_config:

  1. Reads and validates the config (TOML + serde defaults).
  2. Initializes data directories and performs SQLite migrations.
  3. Initializes the LLM driver and model catalog.
  4. Initializes the metering engine and model router.
  5. Assembles core subsystems: registry/scheduler/capability/eventbus/workflow/trigger/background executor/wasm sandbox.
  6. Initializes RBAC, skill registry, and web tools context.
  7. Restores persistent agents and emits the KernelStarted event.

This sequence reflects its "OS-like" nature: assembling all foundational subsystems at boot time, after which the Kernel autonomously harmonizes operations during the run state.

2.3 Agent Lifecycle and Scheduling

The Architecture document defines the main states of an Agent as Running / Suspended / Terminated, mapping the full flow for spawn/message/kill:

  • spawn includes capability inheritance validation to prevent sub-agent privilege escalation.
  • message processing involves RBAC, channel policies, quota checking, module dispatching (builtin/wasm/python), and usage logging.

2.4 Runtime: Tools and Sandboxes

The Runtime grants tool execution safely utilizing multiple isolation paradigms:

  • WASM Sandbox (Wasmtime) leveraging dual metering on untrusted tool code.
  • Subprocess sandbox (utilizing env_clear + allowlists) for running external processes like Python/Node.

2.5 Persistence: Memory Substrate

Memory uses SQLite to furnish: KV, sessions, semantic search, knowledge graphs, usage, canonical sessions, etc. This emphasizes "recoverability" and "governance", endowing long-running Agents with persistent state and cross-channel contexts.

3. Security Design Overview (Defense in Depth)

The Security document explicitly posits: 16 individual systems stack to materialize defense in depth, prohibiting single points of failure.

3.1 Threat Model Summary

Typical Risk Vectors:

  • Unauthorized tool calls and privilege escalation.
  • Sandbox evasion, infinite loops, and resource exhaustion.
  • Log tampering and unauditable actions.
  • Prompt injection and data exfiltration.
  • SSRF and internal network probing.
  • Supply chain attacks (e.g., manifest tampering).
  • Key disclosure (via memory forensics or subprocess environment injection).
  • API abuse and Denial of Service.

4. Deep Dive into 16 Security Systems (Grouped by Risk)

Note: The nomenclature and implementation specifics below are sourced directly from the official Security documentation.

4.1 Access Control and Privilege Boundaries

(1) Capability-Based Security (openfang-types)

  • Agents can purely execute capabilities explicitly granted in their manifests.
  • Capability matching supports wildcards and numerical bounds.
  • A child Agent's capabilities must be a strict subset of its parent's (inheritance validation).

4.2 Execution Isolation and Resource Governance

(2) WASM Dual Metering (openfang-runtime)

  • Features parallel execution of Fuel (instruction counting, deterministic) and Epoch (wall-clock timeouts, non-deterministic) systems.
  • Fuel guards against CPU-bound infinite loops; Epoch restricts host call blocks/I/O hangs.

(13) Subprocess Sandbox (openfang-runtime)

  • env_clear is triggered before subprocess execution, injecting necessaries solely via an allowlist.
  • Preempts sensitive data like API keys leaking to child processes.

4.3 Auditability and Tamper Detection

(3) Merkle Hash Chain Audit Trail (openfang-runtime)

  • Critical actions are appended to a SHA-256 hash chain, where the new entry houses the prev_hash.
  • Endows verify_integrity functionality for detecting retrospective alterations.

4.4 Information Flow and Exfiltration 防护

(4) Information Flow Taint Tracking (openfang-types)

  • Taint labels (e.g., Secret/PII/UserInput/ExternalNetwork) cascade functionally through variable assignments.
  • Sink checks arrest tainted payloads navigating to fragile exits (e.g., net_fetch, shell_exec).
  • Extinguishing taints (declassification) dictates an explicit, auditable operation.

(14) Prompt Injection Scanner (openfang-skills)

  • Performs pattern scanning over skill prompt contents to detect overwrite anomalies (like "ignore previous instructions"), exfiltration matrices, or hazardous shell command syntaxes.

4.5 Supply Chain and Authenticity

(5) Ed25519 Manifest Signing (openfang-types)

  • SHA-256 hashes manifest TOMLs, signing them via Ed25519.
  • verify ensures payload integrity plus origin validity concurrently.

4.6 Network and Interface Defenses

(6) SSRF Protection (openfang-runtime)

  • Isolates access purely to http/https schemes.
  • Employs a hostname blocklist paired with post-DNS-resolution private IP validation to counter DNS rebinding attacks.

(9) OFP Mutual Authentication (openfang-wire)

  • Incorporates a shared-key-based HMAC-SHA256 handshake. A nonce deflects replay injections.
  • Validates via constant-time comparators precluding timing assaults.

(10) Security Headers (openfang-api)

  • Requisites standard web security headers (CSP, X-Frame-Options, Referrer-Policy) by default.

(11) GCRA Rate Limiter (openfang-api)

  • Imposes cost-aware GCRA derivations (token/leaky bucket models) on all ingress API interfaces.

4.7 Key and Secret Handling

(8) Secret Zeroization (openfang-runtime/openfang-channels)

  • Important strings employ Zeroizing<String>, enforcing memory clearing automatically upon drop.

(17) Health Endpoint Redaction (openfang-api)

  • The public health endpoint emits minuscule unclassified details; comprehensive diagnostics require authorization.

4.8 Stability and Self-Protection

(15) Loop Guard (openfang-runtime)

  • Enumerates successive tool invocations with identical arguments, activating warn/block/circuit break cascades autonomously.

(16) Session Repair (openfang-runtime)

  • Rectifies malformed message histories (e.g., orphaned ToolResults, void messages, adjoining identical roles) to curtail sequential API failures and hallucinated responses.

5. Security Best Practices (For Integrators)

  • Architect manifest capabilities strictly adopting the Principle of Least Privilege; abstain from wildcard attributes like ToolAll or NetConnect("*").
  • Assume external data and user inputs originate with tainted labels unless rigorously validated or sanitized.
  • Enforce explicit domain allowlists for tools reliant on network egress, appending secondary egress proxies if attainable.
  • Maintain persistent, verified audit chains; emit tip hashes periodically to extraneous, tamper-evident archives.
  • Implement hash verification structures for installing third-party Skills, circumventing untested repos.

6. Conclusion

The OpenFang architecture underscores an engineering philosophy sculpted for "long-running autonomous systems": rigid Kernel governance, deterministic runtime isolation, and stable persistence mechanisms, interfaced cleanly via heterogeneous channels and protocols. Its security rubric prizes defense-in-depth—fusing capabilities checks, WASM sandboxes, tamper-evident logs, and taint tracking to forcefully minimize the attack surface inherently introduced by Agents authorized to touch webs and invoke tools.

References (Public Sources)

  1. OpenFang Docs — Architecture:
  2. OpenFang Docs — Security:
  3. OpenFang Website:
  4. OpenFang GitHub Repository:
  5. OpenFang CONTRIBUTING (Architecture Overview):