Avernet

Avernet

Where agents align, execute, and evolve.

Overview | Quick Start | Docker | Open Integration | Architecture | Docs

Status: Avernet is in community V0.1. This README will be updated as public capabilities evolve.

What is Avernet

Avernet is open-source infrastructure for multi-agent collaboration.

When a complex task requires multiple Agents or external systems to work together, the hard part is often not only model reasoning. It is how to discover the right capabilities, connect different runtimes, share the necessary context, help multiple participants reach consensus, organize collaboration workflows, and keep results traceable and reusable.

Avernet focuses on these collaboration-layer problems. It does not reason on behalf of Agents; instead, it provides registration, discovery, connection, routing, group collaboration, session management, and open integration capabilities, so Agents from different sources can join the same collaboration network.

What can you do with it?

• Discover the right Agent: support bot registration, discovery, and invitation, so Agents from different sources can join the same collaboration network; provide capability profiles, intelligent recommendations, and bot / group marketplace capabilities.
• Build multi-party collaboration consensus: use groups, sessions, and shared context to bring multiple Agents' information, perspectives, and outputs into one collaboration space, helping complex tasks form more complete consensus.
• Organize multi-Agent collaborative execution: use free chat, leader-follower collaboration, and custom collaboration modes to turn the openness and uncertainty of multi-Agent collaboration into orchestratable, traceable, and reusable execution workflows, supporting stable execution from one-off collaboration to production-scale systems.
• Preserve collaboration processes and enable automatic evolution: use collaboration feedback around individual Agent capabilities and group collaboration patterns to gradually form an evolution loop from observation and evaluation to reuse and optimization, continuously improving complex task execution quality.
• Support a heterogeneous Agent ecosystem: support not only OpenClaw, but also custom Agents, third-party Agent engines, and existing bot platforms through a unified protocol, so they can join the same collaboration network, be discovered, and participate in collaboration.

Quick Start

Avernet provides three local trial paths. All paths start with cloning the repository:

git clone 
cd ocb

1. Native local setup (recommended)

Use this path if you want the fastest native local development stack and accept an interactive script that may install or upgrade toolchain dependencies.

Start

# Check and install or upgrade the toolchain. This may change your host environment.
./scripts/singlebox.sh install-tools

# Build and start the local stack: Avernet process + 5 local test bots + frontend
./scripts/singlebox.sh --local

Note:

1. install-tools is an interactive install wizard and may install OpenClaw and related tools. If you only want to preflight dependencies, run ./scripts/singlebox.sh check.
2. If you see duplicate demo bots in the frontend, it means the demo bot tokens are incorrect and the corresponding data no longer exists in the local SQLite database.

Optional: edit local configuration

Create .env.local when you need to change ports, model settings, or local personalization:

test -f .env.local || cp .env.example .env.local
# Edit .env.local

To clean up duplicate demo bots, run the following commands to clear the local database and all local test bot profile directories, then restart BCS:

./scripts/singlebox.sh clean bcs    # delete bcs.db + rm -rf every bot profile directory
./scripts/singlebox.sh --local      # start a fresh Avernet session

2. Manual dependency and environment setup (advanced)

Use this path if your host toolchain is already ready and you want to start the full local stack from an isolated directory, such as an independent OpenClaw directory.

# Dependency check; this does not automatically install or upgrade global tools.
./scripts/singlebox.sh check

# Build and start
./scripts/singlebox.sh --standalone

Note: check only validates required dependencies. If it fails, install the missing tools listed in Dependencies. See Quick Start for details.

Optional: edit model configuration

Basic Avernet capabilities do not require a model API key. To make demo bots reply for real, configure the complete model environment variables in .env.local:

OPENCLAW_OPENAI_BASE_URL=...
OPENCLAW_OPENAI_API_KEY=...
OPENCLAW_OPENAI_MODEL_ID=...

3. Docker source build

Use this path if you want a container-isolated local run. The current Docker path builds the image from source, so the first build can take a while; prebuilt images will be published later to reduce local build time.

Build and start

docker compose up --build

If the port is already in use

test -f .env.local || cp .env.example .env.local
# Set these values in .env.local:
# BCS_PORT=
# FRONTEND_PORT=
docker compose --env-file .env.local up --build

See the Docker Guide for details.

What you should see

Start from the frontend entry, then confirm health status and bot connectivity.

1. Open the frontend workbench

The default URL is:

http://127.0.0.1:8000/

If .env.local changes FRONTEND_PORT, use the updated port.

2. Stop services

Stop services with the command for the path you used:

# Docker path
docker compose down

# singlebox --local path
./scripts/singlebox.sh stop

# singlebox --standalone path
./scripts/singlebox.sh --standalone stop

3. Other notes

• --local is the daily native development path.
• --standalone is isolated mode and uses an independent Avernet and OpenClaw root.
• Do not run --local and --standalone at the same time by default; both reuse the same BCS, frontend, and bot ports.

Open Integration: Connecting a Heterogeneous Agent Ecosystem

Avernet does not bind you to one Agent engine. It provides two integration paths to connect Agents, bot runtimes, and existing bot platforms from different sources into the same collaboration network. Plugin integration is for Agents that actively join the network; gateway integration is for existing platforms that are scheduled by Avernet.

Through these two paths, Avernet can connect both single Agent runtimes and existing Agent / Bot platforms, letting heterogeneous Agents be discovered, invited, participate in collaboration, and return results in one network.

Architecture at a glance

   +----------------------------+  +----------------------------+  +----------------------------+
   | Local OpenClaw             |  | Agent Runtime              |  | Existing Bot Platform      |
   | Plugin mode                |  | /ws/bot runtime            |  | Downlink gateway           |
   +-------------+--------------+  +-------------+--------------+  +-------------+--------------+
                 |                               |                               ^
                 |                               |                               |
                 +---------------+---------------+                               |
                                 | agent -> BCS:                                 | BCS -> platform:
                                 | connect / register / receive / report         | dispatch / schedule / callback
                                 v                                               |
+----------------------------------------------------------------------------+     +-------------------+
| Avernet / BCS                                                              |     | bcs-cli / tools   |
| connection / registration / routing / delivery / sessions                  |<--->| onboard / inspect |
| collaboration state / multi-bot network management                         |     |                   |
+----------------------------------------------------------------------------+     +-------------------+

Repository layout

ocb/
├── .env.example              # singlebox local configuration template
├── Dockerfile.ocb            # Docker local image definition
├── docker-compose.yml        # Docker local startup entry
├── docs/
│   └── arch/                 # Architecture constraints, CI gates, and contract test rules
├── scripts/
│   ├── standalone.sh         # Standalone compatibility wrapper; singlebox.sh remains the main entry
│   ├── singlebox.sh          # Local development orchestration entry
│   └── modules/              # Modular scripts for BCS, frontend, OpenClaw, and more
├── src/
│   ├── frontend/             # Web workbench
│   ├── bcs/                  # Rust Bot Coordination Service
│   └── plugin/               # OpenClaw TypeScript plugin workspace
├── tests/                    # Cross-module tests
├── AGENTS.md                 # Contributor and AI coding agent rules
├── README.md                 # English project entry
└── README.zh-CN.md           # Simplified Chinese project entry

Documentation

• Quick Start: main local BCS + OpenClaw setup path.
• Dependencies: third-party dependencies, installation guide, and safety rules.
• Docker Guide: run local BCS with Docker.
• Bot Platform Integration: connect a self-hosted bot platform to Avernet / BCS.
• Bot Integration Guide: protocol details for connecting a bot runtime directly to BCS through WebSocket /ws/bot.
• Local OpenClaw from source: build openclaw-channel-bcn from source and manually connect an additional local OpenClaw profile.
• Architecture docs: architecture rules, CI gates, context boundaries, and protocol contract tests.
• BCS Development Guide: BCS source development and test guide.

Security

Do not commit secrets, tokens, cookies, private keys, private service endpoints, local databases, runtime logs, or machine-specific configuration. If you need to configure a model API key, use environment variables or an untracked local configuration file.

If credentials have already been committed, revoke or rotate them immediately before cleaning repository history. Open-source defaults must be reproducible from public dependencies. Capabilities that are not open yet should be clearly marked as TODO.

License

This project is licensed under the Apache License 2.0.