OpenFang Installation and Initialization Guide: From Zero to Your First Agent

Slug: openfang-install-setup-guide Category: usage-guides Target Keywords: OpenFang installation, OpenFang configuration tutorial, OpenFang getting started guide Search Intent: Informational (user wants to deploy OpenFang) Target Word Count: ~1800 words Language: en

What is OpenFang?

OpenFang is a production-grade Agent operating system built on Rust. Unlike traditional AI chat frameworks, OpenFang provides a complete Agent runtime environment—featuring 180ms cold starts, 40MB memory footprint, 16 layers of security, and 40+ channel adapters. Whether you want to run a simple automation task locally or build a cross-platform 24/7 autonomous Agent cluster, OpenFang is up to the task.

This article will guide you through the installation, initialization, and running of your first Agent from scratch.

System Requirements

Before you begin, please ensure your system meets the following minimum requirements:

OpenFang's design philosophy is "lightweight first"—it runs smoothly even on a Raspberry Pi 4 (4GB version).

Step 1: Install the Rust Toolchain

OpenFang is written in Rust, so you first need to install the Rust toolchain:

# Install Rustup (Rust toolchain manager)curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh# Reload environment variablessource "$HOME/.cargo/env"# Verify installationrustc --versioncargo --version

If you already have Rust installed, we recommend updating to the latest stable version:

rustup update stable

Step 2: Install OpenFang

OpenFang offers multiple installation methods; installing directly via Cargo is recommended:

# Install the latest version from crates.iocargo install openfang# Verify installationopenfang --version

If you prefer building from source (suitable for advanced users needing custom configurations):

git clone https://github.com/openfang/openfang.gitcd openfangcargo build --release./target/release/openfang --version

Docker users can also use the official image:

docker pull openfang/openfang:latestdocker run -d --name openfang -v ./config:/app/config openfang/openfang

Step 3: Initialize Configuration

Once installed, run the initialization command to create the configuration file:

# Create default configuration directoryopenfang init# Configuration file location# Linux/macOS: ~/.config/openfang/config.toml# Windows:     %APPDATA%\openfang\config.toml

After initialization, a config.toml file will be generated. Key configuration items include:

[core]name = "my-first-agent"          # Agent nameworkspace = "./workspace"         # Workspace directorylog_level = "info"                # Log level: trace, debug, info, warn, error[claude]api_key = "${ANTHROPIC_API_KEY}"  # Read from environment variablesmodel = "claude-sonnet-5"         # Default modelmax_tokens = 4096[security]sandbox_mode = "strict"           # Sandbox mode: off, basic, strictnetwork_policy = "allowlist"      # Network policyallowed_domains = ["api.anthropic.com"][channels]# Configure at least one channel adapter

Key configuration notes:

• api_key: Supports environment variable references (format ${VAR_NAME}); do not write the API key directly into the configuration file.
• sandbox_mode: strict mode is recommended for production environments.
• network_policy: allowlist mode only allows access to whitelisted domains, while blocklist mode blocks blacklisted domains.
• channels: At least one channel adapter is required; otherwise, the Agent cannot interact with the outside world.

Step 4: Configure Anthropic API Key

OpenFang relies on the Claude API (via Anthropic), which requires an API key:

# Set environment variableexport ANTHROPIC_API_KEY="sk-ant-..."# Recommended: Add to your shell profileecho 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrcsource ~/.bashrc

You can obtain your API key from the Anthropic Console.

Step 5: Select and Configure Channel Adapters

OpenFang supports over 40 channel adapters, allowing Agents to interact with users across different platforms. Common ones include:

Example configuration for Telegram:

[channels.telegram]enabled = truebot_token = "${TELEGRAM_BOT_TOKEN}"allowed_users = ["@your_username"]

Step 6: Launch Your First Agent

Once configured, start the Agent:

# Basic startopenfang start# Specify configuration fileopenfang start --config ./my-config.toml# Run in backgroundopenfang start --daemon# View logsopenfang logs --follow

Upon successful startup, you will see:

⚡ OpenFang v1.0.0├─ Agent: my-first-agent├─ Model: claude-sonnet-5├─ Sandbox: strict├─ Channels: cli└─ Ready. Type /help for commands.

In the CLI channel, you can chat directly with the Agent:

> /help> Check the weather for me today> Analyze the code structure of this GitHub repository

Step 7: Verify Installation

Run the built-in diagnostic command to ensure everything is working correctly:

# Health checkopenfang doctor# Should output something like:# ✅ Rust toolchain: 1.80.0# ✅ Config file: valid# ✅ API key: configured# ✅ Network: ok (latency 45ms)# ✅ Workspace: writable# All checks passed.

FAQ

Next Steps

Congratulations on completing your OpenFang installation and initialization! We recommend reading the following next:

• OpenFang Hands Configuration Guide: Learn how to configure Agent capability modules for different use cases.
• OpenFang Multi-Channel Adapter Configuration: Configure multiple channels simultaneously to make your Agent accessible everywhere.
• OpenFang Security Best Practices: Protect your Agents from attacks.