Bino Swarm 🐐

The autonomous agent framework that doesn't mess around. Build once, deploy everywhere.

Powered by Quicksilver — our open-source framework that bridges Large Language Models (LLMs) with Decentralized Physical Infrastructure Networks (DePINs) to create advanced AI agents.

Originally forked from ElizaOS — credits to the pioneering work that laid the foundation.

See it in action: @Bino_AI • @Caila_AI

✨ What You Get

🛠️ Multi-platform domination: Discord, Twitter, Telegram — your agents go where the action is
🧠 Model buffet: Grok, OpenAI, Anthropic, Gemini — pick your poison, we'll make it work
📚 Document devouring: Feed it anything. PDFs, docs, websites — it reads faster than you and remembers everything
💾 Privacy-first memory: Smart retention that remembers what matters, forgets what doesn't. Auto-deletes old data and wipes everything on user request
🔧 Infinitely hackable: Built to be broken apart and rebuilt. Create custom actions, clients, whatever your heart desires
📦 MCP ready: Connect your own servers because vendor lock-in is for the weak
💸 x402 payments (both directions): run agents as x402 paywalled servers (serve paid endpoints like /:agentId/message-paid via the Direct Client) and as x402 clients (consume other paywalled endpoints via @elizaos/plugin-swarm). See packages/client-direct/README.md and packages/plugin-swarm/README.md.

🎯 What You'll Build

🤖 Chatbots with brains — no more "I don't understand" responses
🕵️ Digital workforce — agents that actually get stuff done while you sleep
📈 Business automation — because manual processes are so 2020
🛡️ Brand guardians — agents that know your brand inside-out, hunt down scammers, and turn FUDders into believers
🎮 NPCs that aren't braindead — give your game characters actual personality
🧠 Trading bots — automate your way to financial freedom (not financial advice, just good code)

🚀 3-Minute Setup (No, Really)

What You Need

Windows folks: You know the drill. WSL 2 or bust.

The Steps (Don't Skip Any)

Give your agent a personality: Copy characters/trump.character.json to characters/my-character.json and make it interesting. Boring agents are useless agents.
Handle your secrets: Copy .env.example to .env and fill in your API keys.
```
cp .env.example .env
```
Pro tip: Skip the .env if you're feeling brave — pass secrets through character JSON instead.
Grab the Docker blueprint: Copy docker-compose.yaml to your project root.

Point it in the right direction: Edit docker-compose.yaml to use your character:

services:
    bino:
        image: ghcr.io/iotexproject/bino:latest # Latest and greatest
        command:
            ["pnpm", "start", "--character=characters/my-character.json"]
# ... rest of your config ...

Fire it up:
```
docker compose up
```
Watch your digital offspring come to life. If it breaks, that's what logs are for.

🛠️ For the Brave: Build From Source

Want to get your hands dirty? Add your own features? Break things properly? Skip the Docker and build it yourself.

Clone and Conquer

git clone https://github.com/iotexproject/binoSwarm.git binoSwarm
cd binoSwarm

Set Up Your Playground

Handle secrets: Same as above — copy .env.example to .env and fill it out.
Create your character: Copy and customize a character file just like the Docker setup.

Build the beast:

pnpm i --no-frozen-lockfile && pnpm build

Let it rip:

pnpm start --character=characters/binotest.json

Now you're running raw code. Break it, fix it, make it better. Pull requests welcome.

📚 Feed Your Agent Knowledge

Your agent is only as smart as what you teach it. Time to make it an expert.

The Knowledge Vault

Drop your knowledge files into characters/knowledge/. Markdown files work great.

Link External Knowledge

Got a knowledge base in another GitHub repo? Don't copy-paste like a peasant — link it:

# Clone your knowledge repo outside the project
git clone https://github.com/your-org/your-docs.git
cd binoSwarm

# Create a symbolic link
ln -s ../your-docs characters/knowledge/your-docs

Tell Your Agent What to Read

Update your character.json to point to the knowledge files:

"knowledge": [
    {
        "path": "iotex2-docs/README.md",
        "shared": false
    },
    {
        "path": "iotex2-docs/depin-infra-modules-dim/ioconnect-hardware-sdk/README.md",
        "shared": false
    }
]

Now your agent knows everything you know. Scary? Maybe. Useful? Absolutely.

🎭 Character Data Sources

Your agent's personality comes from multiple sources, merged in a specific order. Here's how it works:

The Loading Hierarchy

When you start an agent, character data is loaded and merged in this order:

Default Character (packages/core/src/defaultCharacter.ts)
- Used when no character JSON path is provided
- Provides a baseline "Eliza" character with default traits
- Includes system prompt, bio, lore, message examples, and style
Character JSON File (characters/*.json)
- Loaded when you specify --character=characters/my-character.json
- Defines core character properties: name, model provider, plugins, clients
- Can include initial traits, but these get enriched by subsequent sources
Filesystem Traits (characters/agentsTraits/<characterName>/)
- Primary source for character traits (bio, lore, knowledge, templates, etc.)
- Loaded from a directory matching the character's name field
- Structure mirrors GitHub repo format (see below)
- If found, traits are merged with the character JSON
Database Traits (PostgreSQL fallback)
- Fallback when filesystem traits directory doesn't exist
- Maintains backwards compatibility with existing deployments
- Traits stored in characters table with is_published = true

How It Works (HIW)

The merge process follows this flow:

Start Agent
    ↓
Load Character JSON (or use default)
    ↓
Check: Does `characters/agentsTraits/<characterName>/` exist?
    ├─ YES → Load traits from filesystem → Merge → Done
    └─ NO → Check database for traits → Merge → Done

Important: Filesystem traits take precedence over database traits. If both exist, filesystem wins.

GitHub Repo Integration

The filesystem traits directory structure matches a GitHub repository format. Here's how to set it up:

Repository Structure

Your character traits repo should follow this structure:

your-character-repo/
├── bio.json                 # Array of biography strings
├── lore.json                # Array of lore strings
├── knowledge.json           # Array of knowledge paths (strings or objects)
├── messageExamples.json     # Nested array of message examples
├── postExamples.json        # Array of post example strings
├── topics.json              # Array of topic strings
├── adjective.json            # Array of adjective strings
├── style.json               # Style object with all/chat/post arrays
├── templates.json           # Template names mapped to file paths
├── xTargetUsers.txt         # One username per line
├── xKnowledgeUsers.txt      # One username per line
└── prompts/
    ├── system.md            # System prompt (becomes system_prompt)
    ├── goals.md             # Template (becomes templates.goalsTemplate)
    └── *.md                 # Other templates

Setting Up the Symlink

Clone your character traits repo:

git clone https://github.com/your-org/your-character-repo.git

Create a symlink in the project:
```
cd binoSwarm
ln -s ../your-character-repo characters/agentsTraits/your-character-name
```
The directory name must match the name field in your character JSON.

Template Files

The templates.json file maps template names to file paths:

{
    "goalsTemplate": "./prompts/goals.md",
    "twitterQSPrompt": "./prompts/twitterQS.md",
    "memeSystemPrompt": "./prompts/memeSystem.md"
}

The loader reads these files and stores their content in character.templates.

Knowledge Files

knowledge.json can contain either:

Simple strings: ["path/to/file.md"]
Objects with paths: [{"path": "path/to/file.md", "shared": false}]

Both formats are supported and converted to string arrays during loading.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Bino Swarm 🐐

📋 Table of Contents

✨ What You Get

🎯 What You'll Build

🚀 3-Minute Setup (No, Really)

What You Need

The Steps (Don't Skip Any)

🛠️ For the Brave: Build From Source

Clone and Conquer

Set Up Your Playground

📚 Feed Your Agent Knowledge

The Knowledge Vault

Link External Knowledge

Tell Your Agent What to Read

🎭 Character Data Sources

The Loading Hierarchy

How It Works (HIW)

GitHub Repo Integration

Repository Structure

Setting Up the Symlink

Template Files

Knowledge Files

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Bino Swarm 🐐

📋 Table of Contents

✨ What You Get

🎯 What You'll Build

🚀 3-Minute Setup (No, Really)

What You Need

The Steps (Don't Skip Any)

🛠️ For the Brave: Build From Source

Clone and Conquer

Set Up Your Playground

📚 Feed Your Agent Knowledge

The Knowledge Vault

Link External Knowledge

Tell Your Agent What to Read

🎭 Character Data Sources

The Loading Hierarchy

How It Works (HIW)

GitHub Repo Integration

Repository Structure

Setting Up the Symlink

Template Files

Knowledge Files