Quick Start

Get up and running with OpenFang in 5 minutes — install, configure, and spawn your first autonomous agent

This guide will get you from zero to a working OpenFang agent in under 5 minutes.

Prerequisites

• An LLM API key (Anthropic, OpenAI, Groq, or Gemini)
• Terminal access (macOS, Linux, or Windows PowerShell)

If you don’t have an API key yet, we recommend Groq for fast free inference, or Ollama for running models locally.

Installation

1. Install OpenFang

   macOS/Linux

   curl -fsSL https://openfang.sh/install | sh
   

   irm https://openfang.sh/install.ps1 | iex
   

   docker pull ghcr.io/rightnow-ai/openfang:latest
   

   Verify the installation:

   openfang --version
   
2. Initialize configuration

   Run the interactive setup wizard:

   openfang init
   

   The wizard will:

   • Create ~/.openfang/ directory
   • Generate a default config.toml
   • Prompt you to configure an LLM provider

   Use openfang init --quick to skip the wizard and create a minimal config.

3. Configure your LLM provider

   When prompted, choose your provider and paste your API key. The wizard supports:

   • Anthropic (Claude) - Recommended for production
   • OpenAI (GPT-4) - Widest compatibility
   • Groq - Fastest inference, generous free tier
   • Gemini - Google’s models
   • Ollama - Run models locally

   Example for Anthropic:

   Which provider would you like to use? anthropic
   Enter your Anthropic API key: sk-ant-api03-...
   

   The wizard will test your API key and save it to ~/.openfang/config.toml.

   Manual configuration

   If you prefer to configure manually, edit ~/.openfang/config.toml:

   config.toml

   [default_model]
   provider = "anthropic"
   model = "claude-sonnet-4-20250514"
   api_key_env = "ANTHROPIC_API_KEY"
   
   [memory]
   decay_rate = 0.05
   

   Then set your API key as an environment variable:

   export ANTHROPIC_API_KEY="sk-ant-api03-..."
   
4. Start the daemon

   Start the OpenFang daemon:

   openfang start
   

   The daemon will:

   • Boot the kernel and load all subsystems
   • Start the HTTP API server on http://127.0.0.1:4200
   • Initialize the memory substrate (SQLite)
   • Connect to configured channel adapters

   Verify the daemon is running:

   openfang status
   

   Expected output:

   ✓ Daemon is running (PID 12345)
   ✓ API server listening on http://127.0.0.1:4200
   ✓ Memory substrate initialized
   ✓ 0 agents active
   
5. Spawn your first agent

   Create an agent using the researcher template:

   openfang agent new researcher
   

   The CLI will:

   1. Show you the template’s manifest
   2. Prompt for a name (default: “researcher”)
   3. Create and spawn the agent

   Example session:

   $ openfang agent new researcher
   
   Template: researcher
   Description: Deep research agent with web search, fact-checking, and citation
   Tools: web_search, web_fetch, memory_store, memory_recall
   
   Enter agent name (default: researcher): my-researcher
   ✓ Agent spawned: my-researcher (ID: 550e8400-e29b-41d4-a716-446655440000)
   
6. Chat with your agent

   Start an interactive chat session:

   openfang agent chat my-researcher
   

   Try asking a research question:

   You: What are the key architectural differences between OpenFang and LangChain?
   
   my-researcher: Let me research that for you...
   
   [Tool: web_search("OpenFang vs LangChain architecture")]
   [Tool: web_fetch("https://openfang.sh/docs/architecture")]
   [Tool: web_fetch("https://langchain.com/docs/architecture")]
   
   Based on my research, here are the key architectural differences:
   
   1. **Language**: OpenFang is built in Rust (14 crates, 137K LOC), while LangChain is Python-based...
   
   2. **Core Model**: OpenFang is an Agent Operating System with a kernel architecture, whereas LangChain is a library framework...
   
   3. **Execution**: OpenFang agents run autonomously on schedules via "Hands", while LangChain agents are typically invoked programmatically...
   
   [Citations: 5 sources]
   

   Type /help to see available chat commands, or /stop to end the conversation.

What You’ve Built

You now have:

• ✅ OpenFang daemon running
• ✅ HTTP API accessible at http://127.0.0.1:4200
• ✅ A researcher agent with web search capabilities
• ✅ SQLite memory for conversation persistence

Next Steps

Web Dashboard

Open the built-in dashboard to manage agents visually

Create Custom Agents

Build agents with custom tools and prompts

Autonomous Hands

Activate pre-built Hands that work for you 24/7

Connect to Telegram

Deploy your agent to messaging platforms

Try the Dashboard

Open your browser to http://127.0.0.1:4200 to access the WebChat UI:

1. Chat Interface - Message agents with real-time streaming
2. Agent List - View all spawned agents and their status
3. Memory Browser - Explore conversation history
4. System Status - Monitor token usage and costs

Quick Commands Reference

# Daemon management
openfang start                    # Start daemon
openfang stop                     # Stop daemon
openfang status                   # Check status

# Agent operations
openfang agent list               # List all agents
openfang agent chat <name>        # Interactive chat
openfang message <name> "text"    # Send one message
openfang agent kill <name>        # Delete agent

# System info
openfang health                   # Health check
openfang doctor                   # Run diagnostics
openfang logs --follow            # Stream logs

Activate an Autonomous Hand

Hands are pre-built autonomous agents that run on schedules. Try the Researcher Hand:

openfang hand activate researcher

The Researcher Hand will:

• Run daily at a configured time
• Research topics you assign
• Build a knowledge graph of findings
• Deliver reports to your configured channel (Telegram, Discord, etc.)

View active Hands:

openfang hand active

Troubleshooting

Command not found

The installer adds ~/.openfang/bin/ to your PATH, but your shell may need to be restarted:

source ~/.bashrc  # or ~/.zshrc

Or use the full path: ~/.openfang/bin/openfang

API key invalid

Test your API key configuration:

openfang config test-key anthropic

If it fails, reconfigure:

openfang config set-key anthropic

Port 4200 already in use

Change the listen address in ~/.openfang/config.toml:

api_listen = "127.0.0.1:4201"

Then restart: openfang stop && openfang start

Daemon won't start

Run diagnostics:

openfang doctor

Check logs:

openfang logs --lines 50

What’s Next?

Full Installation Guide

Advanced installation options, Docker Compose, systemd services

Configuration

Configure models, channels, security, and memory

Core Concepts

Understand the 14-crate architecture

API Reference

Integrate OpenFang programmatically