LibreFang
中文

Getting Started with LibreFang

This guide walks you through installing LibreFang, configuring your first LLM provider, spawning an agent, and chatting with it.

Project website: https://librefang.ai/

Table of Contents

Installation

Arch Linux repository setup

AUR account registration is temporarily unavailable. LibreFang currently publishes signed Arch packages through its official pacman repository.

Import and locally trust the LibreFang package-signing key:

curl -fsSL https://packages.librefang.ai/librefang.gpg -o /tmp/librefang.gpg
sudo pacman-key --add /tmp/librefang.gpg
sudo pacman-key --finger 2C325B0F88706ED99C45E216DD09DC7D3E70E1E9
sudo pacman-key --lsign-key 2C325B0F88706ED99C45E216DD09DC7D3E70E1E9

Add the repository to /etc/pacman.conf:

[librefang]
Server = https://packages.librefang.ai/arch/$arch

Configure the repository once, then install only the CLI or Desktop package from the corresponding section below. The packages are independent, so installing the CLI is not required for the Desktop app. See the Arch repository documentation for package details and aarch64 support.

CLI

The CLI is the core command-line tool for managing agents, hands, workflows, and more.

Quick Install Script (Recommended)

Linux / macOS / WSL:

curl -fsSL https://librefang.ai/install.sh | sh

Windows (PowerShell):

irm https://librefang.ai/install.ps1 | iex

The script auto-detects platform and architecture, downloads the binary, verifies SHA256 checksums, configures PATH, runs librefang init, and starts the daemon.

Environment variables:

  • LIBREFANG_INSTALL_DIR — install directory (default: ~/.librefang/bin)
  • LIBREFANG_VERSION — specific version (default: latest)
  • LIBREFANG_AUTO_START — auto-start daemon (default: 1)

Windows EXE (Manual)

If you prefer manual installation or the script doesn't work in your environment:

  1. Download librefang-x86_64-pc-windows-msvc.zip (or aarch64 for ARM) from GitHub Releases
  2. Extract librefang.exe to a folder, e.g. C:\Users\<you>\.librefang\bin\
  3. Add that folder to your system PATH:
    • Settings → System → About → Advanced system settings → Environment Variables
    • Edit Path under User variables → Add the folder path
  4. Open a new terminal and run:
# Initialize configuration
librefang init

# Start the daemon
librefang start

# Open dashboard in browser: http://127.0.0.1:4545/
# Chat with the default agent
librefang chat

librefang init creates ~/.librefang/config.toml with a setup wizard. You must run init before start — otherwise the daemon has no configuration. On first run, if init has not been run, start and chat will auto-initialize.

Homebrew (macOS / Linux)

brew tap librefang/tap
brew install librefang              # Stable
brew install librefang-beta         # Beta
brew install librefang-rc           # RC

Arch Linux (pacman)

sudo pacman -Syu librefang-bin

This installs the CLI, daemon, HTTP API, and web dashboard without the Desktop app.

npm

npm install -g @librefang/cli                  # Stable
npm install -g @librefang/cli@next             # Latest pre-release (Beta or RC)
npm install -g @librefang/[email protected]    # Specific version

pip

pip install librefang-cli                      # Stable
pip install librefang-cli --pre                # Latest pre-release

Cargo

cargo install --git https://github.com/librefang/librefang librefang-cli

Or build from source (requires just):

git clone https://github.com/librefang/librefang.git
cd librefang
just install

Docker

docker run -d \
  --name librefang \
  -p 4545:4545 \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v librefang-data:/data \
  ghcr.io/librefang/librefang:latest

Docker Compose:

git clone https://github.com/librefang/librefang.git
cd librefang/deploy
docker compose up -d

Verify Installation

librefang --version

SDK

SDKs for integrating LibreFang API into your applications.

JavaScript / TypeScript

npm install @librefang/sdk                     # Stable
npm install @librefang/sdk@next                # Latest pre-release (Beta or RC)
npm install @librefang/[email protected]       # Specific version

Python

pip install librefang-sdk                      # Stable
pip install librefang-sdk --pre                # Latest pre-release (Beta or RC)
pip install librefang-sdk==2026.3.25rc1        # Specific version (PEP 440)

Rust

cargo add librefang

Go

go get github.com/librefang/librefang/sdk/go

Desktop App

Native Tauri 2.0 desktop application. See Desktop for details.

Homebrew Cask

brew tap librefang/tap
brew install --cask librefang       # Stable
brew install --cask librefang-beta  # Beta
brew install --cask librefang-rc    # RC

Arch Linux (pacman)

After completing the Arch Linux repository setup:

sudo pacman -Syu librefang-desktop-bin

The Desktop package is standalone and does not require librefang-bin. The desktop package is available on x86_64 only. On aarch64, use librefang-bin for the native service or librefang-docker for the Docker-backed systemd service, then open the web dashboard at http://127.0.0.1:4545/.

Direct Download

Download from GitHub Releases:

  • macOS: .dmg (Universal)
  • Windows: .msi
  • Linux: .appimage / .deb

One-Click Cloud Deployment

Visit deploy.librefang.ai for all cloud deployment options.

Fly.io

curl -sL https://raw.githubusercontent.com/librefang/librefang/main/deploy/fly/deploy.sh | bash

Railway

Railway

Render

Render

GCP (Terraform)

Deploy on GCP always-free tier (e2-micro). See deploy/gcp/README.md for details:

cd deploy/gcp
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your project_id and API keys
terraform init && terraform apply

Linux systemd

sudo cp deploy/librefang.service /etc/systemd/system/
sudo systemctl enable --now librefang

Configuration

Initialize

Initialization runs automatically on first librefang start (or via the install script / Docker entrypoint). To run the interactive setup wizard manually:

librefang init

This creates the ~/.librefang/ directory (customizable via LIBREFANG_HOME):

~/.librefang/
├── config.toml                # Main configuration file
├── aliases.toml               # Model and command aliases
├── data/
│   ├── librefang.db           #   SQLite database (memory, sessions, knowledge graph)
│   └── state.db               #   Daemon state persistence
├── registry/                  # Synced from librefang-registry
│   ├── agents/                #   32 agent templates
│   ├── hands/                 #   15 hand definitions
│   ├── providers/             #   49 provider configs
│   ├── skills/                #   Skill definitions
│   ├── workflows/             #   Workflow templates
│   └── plugins/               #   Plugin definitions
├── workspaces/                # Runtime working directories
│   ├── agents/                #   Active agent working directories
│   └── hands/                 #   Active hand working directories
├── skills/                    # User-installed skills
├── plugins/                   # User-installed plugins
├── vault.enc                  # Encrypted credential vault
├── logs/                      # Application logs
├── cache/                     # Temporary cache
└── bin/                       # CLI binary (if installed via script)

See Architecture - User Data Directory for the full reference.

Set Up an API Key

LibreFang 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.

LibreFang supports three layers of key storage (highest priority first):

LayerFileHow to setNotes
System env vars—export GROQ_API_KEY=...Highest priority, never overridden
Encrypted vaultvault.enclibrefang vault set GROQ_API_KEYAES encrypted, recommended
.env file.envlibrefang config set-key groqPlaintext, written by CLI
secrets.envsecrets.envDashboard "Set API Key" buttonPlaintext, written by dashboard

Edit the Config

The default config uses Anthropic. To change the provider, edit ~/.librefang/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:4545"        # OFP listen address

Verify Your Setup

librefang doctor

This checks that your config exists, API keys are set, and the toolchain is available.

Spawn Your First Agent

Using a Built-in Template

LibreFang provides 32 agent templates from the registry (assistant pre-installed, others available from dashboard). Spawn the assistant agent:

librefang agent spawn agents/hello-world/agent.toml

Output:

Agent spawned successfully!
  ID:   a1b2c3d4-e5f6-...
  Name: hello-world

Using a Custom Manifest

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:

librefang agent spawn my-agent.toml

List Running Agents

librefang agent list

Output:

ID                                     NAME             STATE      PROVIDER     MODEL
-----------------------------------------------------------------------------------------------
a1b2c3d4-e5f6-...                     hello-world      Running    groq         llama-3.3-70b-versatile

Chat with an Agent

Start an interactive chat session using the agent ID:

librefang agent chat a1b2c3d4-e5f6-...

Or use the quick chat command (picks the first available agent):

librefang chat

Or specify an agent by name:

librefang 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 LibreFang. 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.

Start the Daemon

For persistent agents, multi-user access, and the WebChat UI, start the daemon:

librefang start

Output:

Starting LibreFang daemon...
LibreFang daemon running on http://127.0.0.1:4545
Press Ctrl+C to stop.

The daemon provides:

  • REST API at http://127.0.0.1:4545/api/
  • WebSocket endpoint at ws://127.0.0.1:4545/api/agents/{id}/ws
  • WebChat UI at http://127.0.0.1:4545/
  • OFP networking on port 4545

Check Status

librefang status

Stop the Daemon

Press Ctrl+C in the terminal running the daemon, or:

curl -X POST http://127.0.0.1:4545/api/shutdown

Using the WebChat UI

With the daemon running, open your browser to:

http://127.0.0.1:4545/

The embedded WebChat UI allows you to:

  • View all running agents
  • Chat with any agent in real-time (via WebSocket)
  • See streaming responses as they are generated
  • View token usage per message

Next Steps

Now that you have LibreFang running:

  • Explore agent templates: Browse the agents/ directory for pre-built agents (coder, researcher, writer, ops, analyst, security-auditor, and more).
  • Create custom agents: Write your own agent.toml manifests. See the Architecture guide for details on capabilities and scheduling.
  • Set up channels: Connect any of 44 messaging platforms (Telegram, Discord, Slack, WhatsApp, LINE, Mastodon, and 38 more). See Channel Adapters.
  • Install skills: 60 expert knowledge skills available from the dashboard (GitHub, Docker, Kubernetes, security audit, prompt engineering, etc.). See Skill Development.
  • Build custom skills: Extend agents with Python, WASM, or prompt-only skills. See Skill Development.
  • Use the API: 230+ REST/WS/SSE endpoints, including an OpenAI-compatible /v1/chat/completions. See API Reference.
  • Switch LLM providers: 49 drivers supported (Anthropic, OpenAI, Gemini, Groq, DeepSeek, xAI, Ollama, and more). Per-agent model overrides.
  • Set up workflows: Chain multiple agents together. Use librefang workflow create with a TOML workflow definition.
  • Use MCP: Connect to external tools via Model Context Protocol. Configure in config.toml under [[mcp_servers]].
  • Migrate from OpenFang: Run librefang migrate --from openfang. Copies ~/.openfang → ~/.librefang with automatic content rewriting.
  • Migrate from OpenClaw: Run librefang migrate --from openclaw. See MIGRATION.md.
  • Desktop app: Run cargo tauri dev for a native desktop experience with system tray.
  • Run diagnostics: librefang doctor checks your entire setup.

Useful Commands Reference

librefang init                          # Initialize ~/.librefang/
librefang start                         # Start the daemon
librefang status                        # Check daemon status
librefang doctor                        # Run diagnostic checks

librefang agent spawn <manifest.toml>   # Spawn an agent
librefang agent list                    # List all agents
librefang agent chat <id>               # Chat with an agent
librefang agent kill <id>               # Kill an agent

librefang workflow list                 # List workflows
librefang workflow create <file.json>   # Create a workflow
librefang workflow run <id> <input>     # Run a workflow

librefang trigger list                  # List event triggers
librefang trigger create <args>         # Create a trigger
librefang trigger delete <id>           # Delete a trigger

librefang skill install <source>        # Install a skill
librefang skill list                    # List installed skills
librefang skill search <query>          # Search FangHub
librefang skill create                  # Scaffold a new skill

librefang channel list                  # Show configured channels
librefang channel setup <channel>       # Schema-driven sidecar setup
librefang channel reload                # Hot-reload after config.toml edits
librefang channel rm <channel>          # Drop a sidecar entry + reload

librefang config show                   # Show current config
librefang config edit                   # Open config in editor

librefang chat [agent]                  # Quick chat (alias)
librefang migrate --from openfang       # Migrate from OpenFang
librefang migrate --from openclaw       # Migrate from OpenClaw
librefang mcp                           # Start MCP server (stdio)