Installation - OpenFang

System requirements

OpenFang is a single ~32MB binary with zero runtime dependencies. It runs on:

Operating Systems: macOS (10.15+), Linux (glibc 2.31+), Windows (10/11), Docker
Architectures: x86_64 (Intel/AMD), ARM64 (Apple Silicon, AWS Graviton)
Memory: 100MB minimum, 512MB recommended
Disk: 100MB for binary + data
Network: Optional (for LLM API calls and channel integrations)

OpenFang can run fully offline if you use a local LLM provider like Ollama.

Installation methods

Choose the method that works best for your platform:

One-line installer

Recommended for macOS/Linux

PowerShell installer

Recommended for Windows

Docker

For containerized deployments

Build from source

For contributors and custom builds

macOS installation

One-line installer (recommended)

The installer downloads the latest pre-built binary, verifies the checksum, and adds it to your PATH.

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

What it does:

Detects your architecture (Intel x86_64 or Apple Silicon ARM64)
Downloads the latest release from GitHub
Verifies SHA256 checksum
Installs to ~/.openfang/bin/openfang
Adds ~/.openfang/bin to your PATH (in ~/.zshrc or ~/.bashrc)

Apple Silicon users: The installer automatically downloads the ARM64 binary optimized for M1/M2/M3 chips.

Homebrew (coming soon)

brew install openfang

Homebrew formula is in progress. Use the one-line installer for now.

Verify installation

openfang --version

Expected output:

openfang 0.3.24

Update OpenFang

Re-run the installer to upgrade to the latest version:

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

Or manually download a specific version:

export OPENFANG_VERSION=v0.3.24
curl -fsSL https://openfang.sh/install | sh

Linux installation

One-line installer (recommended)

Works on Ubuntu, Debian, Fedora, Arch, and most glibc-based distributions:

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

Supported distributions:

Ubuntu 20.04+ (Focal, Jammy, Noble)
Debian 11+ (Bullseye, Bookworm)
Fedora 36+
Arch Linux (rolling)
RHEL/CentOS 8+
Amazon Linux 2023
Any glibc 2.31+ distribution

Install to a custom directory

export OPENFANG_INSTALL_DIR=/usr/local/bin
curl -fsSL https://openfang.sh/install | sh

If you install to a system directory like /usr/local/bin, you may need sudo privileges.

Package managers

sudo apt-get install openfang

Official packages are in progress. Use the one-line installer for now.

Verify installation

openfang --version

Add to systemd (run as a service)

Create a systemd service file to run OpenFang automatically on boot:

sudo tee /etc/systemd/system/openfang.service > /dev/null <<EOF
[Unit]
Description=OpenFang Agent Operating System
After=network.target

[Service]
Type=simple
User=$USER
Environment="GROQ_API_KEY=your_key_here"
ExecStart=$HOME/.openfang/bin/openfang start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable openfang
sudo systemctl start openfang

Check status:

sudo systemctl status openfang

Windows installation

PowerShell installer (recommended)

Run this command in PowerShell (right-click → Run as Administrator if needed):

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

What it does:

Detects your architecture (x64 or ARM64)
Downloads the latest release (.zip)
Verifies SHA256 checksum
Extracts openfang.exe to %USERPROFILE%\.openfang\bin
Adds the directory to your user PATH

Restart your terminal (CMD, PowerShell, or Git Bash) after installation for PATH changes to take effect.

Windows Subsystem for Linux (WSL)

If you’re using WSL2, follow the Linux installation instructions inside your WSL environment.

# Inside WSL
curl -fsSL https://openfang.sh/install | sh

Verify installation

Open a new PowerShell or CMD window and run:

openfang --version

Expected output:

openfang 0.3.24

MSI installer (coming soon)

Double-click to install with a GUI wizard:

OpenFang-0.3.24-x64.msi

MSI installer is in development. Use the PowerShell script for now.

Run as a Windows service

Use NSSM (Non-Sucking Service Manager) to run OpenFang as a background service:

# Download NSSM
choco install nssm

# Create service
nssm install OpenFang "C:\Users\YourName\.openfang\bin\openfang.exe" "start"
nssm set OpenFang AppDirectory "C:\Users\YourName\.openfang"
nssm set OpenFang AppEnvironmentExtra "GROQ_API_KEY=your_key_here"

# Start service
nssm start OpenFang

Docker installation

Official image

Pull the latest OpenFang image from Docker Hub:

docker pull rightnow/openfang:latest

Run OpenFang in a container

Start the daemon with persistent storage:

docker run -d \
  --name openfang \
  -p 4200:4200 \
  -v openfang-data:/data \
  -e GROQ_API_KEY=your_key_here \
  rightnow/openfang:latest

The -v openfang-data:/data volume persists agent configurations, conversations, and memory between container restarts.

Access the dashboard

Open http://localhost:4200 in your browser.

Run a one-off command

Execute OpenFang CLI commands inside the container:

docker exec -it openfang openfang agent list
docker exec -it openfang openfang chat researcher

Docker Compose

Create a docker-compose.yml file:

docker-compose.yml

version: '3.8'

services:
  openfang:
    image: rightnow/openfang:latest
    container_name: openfang
    ports:
      - "4200:4200"
    volumes:
      - openfang-data:/data
    environment:
      GROQ_API_KEY: ${GROQ_API_KEY}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      OPENAI_API_KEY: ${OPENAI_API_KEY}
    restart: unless-stopped

volumes:
  openfang-data:

Start the service:

docker-compose up -d

Build your own Docker image

Clone the repository and build locally:

git clone https://github.com/RightNow-AI/openfang.git
cd openfang
docker build -t openfang:custom .
docker run -d -p 4200:4200 -v openfang-data:/data openfang:custom

Build from source

Prerequisites

Install Rust 1.75 or later:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update

Clone the repository

git clone https://github.com/RightNow-AI/openfang.git
cd openfang

Build the project

OpenFang is a Cargo workspace with 14 crates:

cargo build --release

The first build takes 5-10 minutes because it compiles SQLite (bundled) and Wasmtime. Subsequent builds are incremental and much faster.

Install the binary

Copy the compiled binary to a directory in your PATH:

sudo cp target/release/openfang /usr/local/bin/
# or
cp target/release/openfang ~/.openfang/bin/

Run tests

OpenFang has 1,744+ tests covering all subsystems:

cargo test --workspace

Run clippy (zero warnings policy)

cargo clippy --workspace --all-targets -- -D warnings

Development build

For faster compile times during development:

cargo build              # Debug build (no optimizations)
cargo run -- --help      # Run directly without installing

Configuration

After installation, initialize OpenFang:

openfang init

This creates:

~/.openfang/config.toml — Main configuration file
~/.openfang/.env — Environment variables for API keys
~/.openfang/data/openfang.db — SQLite database
~/.openfang/logs/ — Log files

Example configuration

~/.openfang/config.toml:

# API server settings
api_listen = "127.0.0.1:4200"
# api_key = "your_secret_key"  # Uncomment to enable auth

[default_model]
provider = "groq"
model = "llama-3.3-70b-versatile"
api_key_env = "GROQ_API_KEY"

[memory]
decay_rate = 0.05

[network]
listen_addr = "127.0.0.1:4200"

~/.openfang/.env:

GROQ_API_KEY=gsk_your_key_here
ANTHROPIC_API_KEY=sk-ant-your_key_here
OPENAI_API_KEY=sk-your_key_here

Environment variables

OpenFang respects the following environment variables:

Variable	Description	Default
`OPENFANG_HOME`	Data directory	`~/.openfang`
`OPENFANG_LISTEN`	API server bind address	`127.0.0.1:4200`
`OPENFANG_API_KEY`	API authentication key	None (localhost-only)
`RUST_LOG`	Log level	`info`
`GROQ_API_KEY`	Groq API key	None
`ANTHROPIC_API_KEY`	Anthropic (Claude) API key	None
`OPENAI_API_KEY`	OpenAI API key	None
`GEMINI_API_KEY`	Google Gemini API key	None
`OLLAMA_BASE_URL`	Ollama endpoint	`http://localhost:11434`

Set them in your shell profile or in ~/.openfang/.env for persistence.

Updating OpenFang

Update via installer

Re-run the installation script:

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

Update Docker image

docker pull rightnow/openfang:latest
docker-compose down
docker-compose up -d

Update from source

cd openfang
git pull origin main
cargo build --release
sudo cp target/release/openfang /usr/local/bin/

Uninstalling OpenFang

Remove the binary

rm -rf ~/.openfang
# Also remove PATH entry from ~/.bashrc or ~/.zshrc

Or use the built-in uninstaller

openfang uninstall

This removes:

The binary (~/.openfang/bin/openfang)
Configuration files (~/.openfang/config.toml)
Database and logs (~/.openfang/data/)
PATH entries from shell config files

The uninstaller permanently deletes all agent data, conversations, and memory. Back up ~/.openfang/data/ first if you want to preserve it.

Troubleshooting

Installation fails with SSL error

The installer requires HTTPS to download from GitHub. Ensure you have up-to-date SSL certificates.Fix (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install ca-certificates

Fix (macOS):

brew update
brew upgrade openssl

Permission denied when running openfang

The binary may not have execute permissions.Fix:

chmod +x ~/.openfang/bin/openfang

Command not found after installation

The installer added ~/.openfang/bin to your PATH, but you may need to restart your terminal.Fix:

# Temporarily add to PATH
export PATH="$HOME/.openfang/bin:$PATH"

# Or reload your shell config
source ~/.bashrc  # or ~/.zshrc

Checksum verification failed

The download may be corrupted or tampered with.Fix:

# Clear cache and retry
rm -rf /tmp/openfang-install
curl -fsSL https://openfang.sh/install | sh

If the issue persists, report it on GitHub.

Docker container exits immediately

Check the container logs for errors:

docker logs openfang

Common causes:

Missing API key: Add -e GROQ_API_KEY=... to the docker run command
Port conflict: Change -p 4200:4200 to -p 5000:4200

Build from source fails

Ensure you have Rust 1.75+ installed:

rustc --version
rustup update

If the build fails, check CONTRIBUTING.md for detailed build instructions.

Next steps

Now that OpenFang is installed, continue with the Quickstart to:

Initialize configuration with openfang init
Start the daemon with openfang start
Spawn your first agent with openfang agent spawn researcher
Chat with the agent using openfang chat researcher

Quickstart Guide

Get your first agent running in 5 minutes

Configuration

Configure models, channels, and security

Creating Agents

Create custom agents with templates

API Reference

Integrate OpenFang programmatically

Get help

Discord

Ask questions and get support

GitHub Issues

Report bugs or request features

Twitter/X

Follow for updates

Get Started

Core Concepts

Autonomous Hands

Configuration

Integrations

Guides

​System requirements

​Installation methods

One-line installer

PowerShell installer

Docker

Build from source

​macOS installation

​One-line installer (recommended)

​Homebrew (coming soon)

​Verify installation

​Update OpenFang

​Linux installation

​One-line installer (recommended)

​Install to a custom directory

​Package managers

​Verify installation

​Add to systemd (run as a service)

​Windows installation

​PowerShell installer (recommended)

​Windows Subsystem for Linux (WSL)

​Verify installation

​MSI installer (coming soon)

​Run as a Windows service

​Docker installation

​Official image

​Run OpenFang in a container

​Access the dashboard

​Run a one-off command

​Docker Compose

​Build your own Docker image

​Build from source

​Prerequisites

​Clone the repository

​Build the project

​Install the binary

​Run tests

​Run clippy (zero warnings policy)

​Development build

​Configuration

​Example configuration

​Environment variables

​Updating OpenFang

​Update via installer

​Update Docker image

​Update from source

​Uninstalling OpenFang

​Remove the binary

​Or use the built-in uninstaller

​Troubleshooting

​Next steps

Quickstart Guide

Configuration

Creating Agents

API Reference

​Get help

Discord

GitHub Issues

Twitter/X

System requirements

Installation methods

macOS installation

One-line installer (recommended)

Homebrew (coming soon)

Verify installation

Update OpenFang

Linux installation

One-line installer (recommended)

Install to a custom directory

Package managers

Verify installation

Add to systemd (run as a service)

Windows installation

PowerShell installer (recommended)

Windows Subsystem for Linux (WSL)

Verify installation

MSI installer (coming soon)

Run as a Windows service

Docker installation

Official image

Run OpenFang in a container

Access the dashboard

Run a one-off command

Docker Compose

Build your own Docker image

Build from source

Prerequisites

Clone the repository

Build the project

Install the binary

Run tests

Run clippy (zero warnings policy)

Development build

Configuration

Example configuration

Environment variables

Updating OpenFang

Update via installer

Update Docker image

Update from source

Uninstalling OpenFang

Remove the binary

Or use the built-in uninstaller

Troubleshooting

Next steps

Get help