docs/getting-started.md
This guide walks you through installing OpenFang, configuring your first LLM provider, spawning an agent, and chatting with it.
Download the installer for your platform from the latest release:
| Platform | File |
|---|---|
| Windows | .msi installer |
| macOS | .dmg disk image |
| Linux | .AppImage or .deb |
The desktop app includes the full OpenFang system with a native window, system tray, auto-updates, and OS notifications. Updates are installed automatically in the background.
curl -sSf https://openfang.sh | sh
This downloads the latest CLI binary and installs it to ~/.openfang/bin/.
irm https://openfang.sh/install.ps1 | iex
Downloads the latest CLI binary, verifies its SHA256 checksum, and adds it to your user PATH.
Requires Rust 1.75+:
cargo install --git https://github.com/RightNow-AI/openfang openfang-cli
Or build from source:
git clone https://github.com/RightNow-AI/openfang.git
cd openfang
cargo install --path crates/openfang-cli
docker pull ghcr.io/RightNow-AI/openfang:latest
docker run -d \
--name openfang \
-p 4200:4200 \
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
-v openfang-data:/data \
ghcr.io/RightNow-AI/openfang:latest
Or use Docker Compose:
git clone https://github.com/RightNow-AI/openfang.git
cd openfang
# Set your API keys in environment or .env file
docker compose up -d
openfang --version
Run the init command to create the ~/.openfang/ directory and a default config file:
openfang init
This creates:
~/.openfang/
config.toml # Main configuration
data/ # Database and runtime data
agents/ # Agent manifests (optional)
OpenFang needs at least one LLM provider API key. Set it as an environment variable:
# Anthropic (Claude)
export ANTHROPIC_API_KEY=sk-ant-...
# Or OpenAI
export OPENAI_API_KEY=sk-...
# Or Groq (free tier available)
export GROQ_API_KEY=gsk_...
Add the export to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist it.
The default config uses Anthropic. To change the provider, edit ~/.openfang/config.toml:
[default_model]
provider = "groq" # anthropic, openai, groq, ollama, etc.
model = "llama-3.3-70b-versatile" # Model identifier for the provider
api_key_env = "GROQ_API_KEY" # Env var holding the API key
[memory]
decay_rate = 0.05 # Memory confidence decay rate
[network]
listen_addr = "127.0.0.1:4200" # OFP listen address
openfang doctor
This checks that your config exists, API keys are set, and the toolchain is available.
OpenFang ships with 30 agent templates. Spawn the hello-world agent:
openfang agent spawn agents/hello-world/agent.toml
Output:
Agent spawned successfully!
ID: a1b2c3d4-e5f6-...
Name: hello-world
Create your own my-agent.toml:
name = "my-assistant"
version = "0.1.0"
description = "A helpful assistant"
author = "you"
module = "builtin:chat"
[model]
provider = "groq"
model = "llama-3.3-70b-versatile"
[capabilities]
tools = ["file_read", "file_list", "web_fetch"]
memory_read = ["*"]
memory_write = ["self.*"]
Then spawn it:
openfang agent spawn my-agent.toml
openfang agent list
Output:
ID NAME STATE PROVIDER MODEL
-----------------------------------------------------------------------------------------------
a1b2c3d4-e5f6-... hello-world Running groq llama-3.3-70b-versatile
Start an interactive chat session using the agent ID:
openfang agent chat a1b2c3d4-e5f6-...
Or use the quick chat command (picks the first available agent):
openfang chat
Or specify an agent by name:
openfang chat hello-world
Example session:
Chat session started (daemon mode). Type 'exit' or Ctrl+C to quit.
you> Hello! What can you do?
agent> I'm the hello-world agent running on OpenFang. I can:
- Read files from the filesystem
- List directory contents
- Fetch web pages
Try asking me to read a file or look up something on the web!
[tokens: 142 in / 87 out | iterations: 1]
you> List the files in the current directory
agent> Here are the files in the current directory:
- Cargo.toml
- Cargo.lock
- README.md
- agents/
- crates/
- docs/
...
you> exit
Chat session ended.
For persistent agents, multi-user access, and the WebChat UI, start the daemon:
openfang start
Output:
Starting OpenFang daemon...
OpenFang daemon running on http://127.0.0.1:4200
Press Ctrl+C to stop.
The daemon provides:
http://127.0.0.1:4200/api/ws://127.0.0.1:4200/api/agents/{id}/wshttp://127.0.0.1:4200/openfang status
Press Ctrl+C in the terminal running the daemon, or:
curl -X POST http://127.0.0.1:4200/api/shutdown
With the daemon running, open your browser to:
http://127.0.0.1:4200/
The embedded WebChat UI allows you to:
Now that you have OpenFang running:
agents/ directory for 30 pre-built agents (coder, researcher, writer, ops, analyst, security-auditor, and more).agent.toml manifests. See the Architecture guide for details on capabilities and scheduling./v1/chat/completions. See API Reference.openfang workflow create with a TOML workflow definition.config.toml under [[mcp_servers]].openfang migrate --from openclaw. See MIGRATION.md.cargo tauri dev for a native desktop experience with system tray.openfang doctor checks your entire setup.openfang init # Initialize ~/.openfang/
openfang start # Start the daemon
openfang status # Check daemon status
openfang doctor # Run diagnostic checks
openfang agent spawn <manifest.toml> # Spawn an agent
openfang agent list # List all agents
openfang agent chat <id> # Chat with an agent
openfang agent kill <id> # Kill an agent
openfang workflow list # List workflows
openfang workflow create <file.json> # Create a workflow
openfang workflow run <id> <input> # Run a workflow
openfang trigger list # List event triggers
openfang trigger create <args> # Create a trigger
openfang trigger delete <id> # Delete a trigger
openfang skill install <source> # Install a skill
openfang skill list # List installed skills
openfang skill search <query> # Search FangHub
openfang skill create # Scaffold a new skill
openfang channel list # List channel status
openfang channel setup <channel> # Interactive setup wizard
openfang config show # Show current config
openfang config edit # Open config in editor
openfang chat [agent] # Quick chat (alias)
openfang migrate --from openclaw # Migrate from OpenClaw
openfang mcp # Start MCP server (stdio)