PeerClaw

Decentralized P2P AI Agent Network

One binary. Distributed intelligence. Token-powered autonomy.

Overview

PeerClaw is a peer-to-peer network where AI agents collaborate, share compute resources, and transact using a native token economy. Think BitTorrent meets AI inference — every peer contributes compute and earns tokens, while agents spend tokens to execute tasks across the network.

Ships as a single static binary. No containers, no orchestrators, no cloud dependencies.

Key Features

Local AI inference — Run GGUF models (Llama, Phi, Qwen, Gemma) with Metal/CUDA acceleration, streaming, and batch aggregation
P2P networking — Decentralized peer discovery via libp2p (Kademlia, GossipSub, mDNS, Noise encryption)
Agent runtime — ReAct loop with tool calling, budget enforcement, and TOML-defined agent specs
Token economy — PCLAW token accounting, escrow, and budget limits (per-request/hour/day/total)
Multi-agent orchestration — Visual workflow builder, multi-step pipelines, P2P workflow market
Vector memory — Semantic search (HNSW + BM25 hybrid) with cross-session learning
Tools & MCP — 20+ builtin tools, WASM sandbox, and Model Context Protocol integration
LLM provider sharing — Share your Ollama/GGUF models over P2P and earn CLAW tokens
Web dashboard — Agentic chat, workflow builder, network topology, task management
Safety layer — Leak detection, prompt injection defense, content policy enforcement
OpenAI-compatible API — Drop-in replacement with SSE streaming

Supported Backends

Inference

Backend	Status	Notes
Local GGUF	✅	Direct model loading via llama-cpp-2
Ollama	✅	Automatic model management and GPU acceleration
Remote API	✅	OpenAI, Anthropic, Groq, Together, OpenRouter, or any compatible endpoint
P2P Providers	✅	Use LLMs from other peers on the network (costs CLAW tokens)

Messaging Channels

Platform	Status	Notes
REPL	✅	CLI stdin/stdout interaction
WebSocket	✅	Used by the web dashboard chat
Webhook	✅	HTTP POST endpoint, configurable port
Telegram	✅	Native Bot API integration (long polling)

Screenshots

Chat — Agentic assistant with tool calling

Agent Builder — Visual workflow editor

Setup Wizard — Model downloads and configuration

Tools — Browse, inspect, and execute

P2P Network — Peer topology & connections

Settings — Inference backends

Skills — Template library

Quick Start

Docker (recommended)

git clone https://github.com/antonellof/peerclaw.git
cd peerclaw
docker compose up --build
# Open http://localhost:8080 — the setup wizard guides you through configuration

Make sure Ollama is running on your host (ollama serve).

Build from source

git clone https://github.com/antonellof/peerclaw.git
cd peerclaw
cargo build --release

Download a model

mkdir -p ~/.peerclaw/models
curl -L -o ~/.peerclaw/models/llama-3.2-1b-instruct-q4_k_m.gguf \
  "https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_K_M.gguf"

Run

# Interactive chat (Ollama-style)
peerclaw run llama-3.2-1b

# Full-featured chat with slash commands
peerclaw chat

# Start peer node with web dashboard
peerclaw serve --web 127.0.0.1:8080

# With Ollama + personal assistant agent
peerclaw serve --web 127.0.0.1:8080 --ollama --agent templates/agents/assistant.toml

# Share your LLM with the network (earn CLAW tokens)
peerclaw serve --web 127.0.0.1:8080 --ollama --share-inference

Web Dashboard

The dashboard ships with the binary and is served via --web.

Feature	Description
Agentic chat	ReAct loop with tool calling, MCP support, session history
Workflow builder	Visual node editor for multi-step agent pipelines
Agent library	Browse, edit, and instantiate saved workflows
Task management	Create, monitor, and inspect agent task results with tool traces
Network topology	Interactive D3.js graph with clickable node details
Provider settings	Configure LLM sharing, view discovered network providers
MCP console	Add/edit MCP servers, inspect connection status
Setup wizard	Guided onboarding for inference, models, and MCP

Built-in Agent Templates

PeerClaw ships with multi-step agent pipelines (not just single-LLM wrappers):

Agent	Pipeline	Description
Deep Researcher	Classify → Guardrail → Research → Synthesize	Safety check, thorough investigation, polished report
Code Reviewer	Analyze → Refactor → Format	Structured analysis, refactoring suggestions, severity levels
Creative Writer	Classify → Outline → Draft → Edit	Genre detection, outline, full draft, editor polish
Data Analyst	Understand → Analyze → Recommend	Parse request, execute analysis, actionable insights

Select any agent in Chat → Agents dropdown, or build your own in the Workflow builder.

Built-in Tools

Tool	Description
`web_search`	DuckDuckGo search (no API key)
`web_fetch`	Fetch and extract text from web pages
`browser`	Headless browser automation
`file_read` / `file_write` / `file_list`	Filesystem operations
`shell`	Sandboxed shell command execution
`code_exec`	Python, JavaScript, Bash, Ruby in sandbox
`http`	HTTP requests (GET, POST, PUT, DELETE, PATCH)
`memory_search` / `memory_write`	Vector semantic memory (cross-session)
`job_submit` / `job_status`	P2P marketplace jobs (costs CLAW tokens)
`agent_spawn`	Spawn sub-agents with independent context
`llm_task`	Delegate sub-tasks to another LLM call
`peer_discovery`	Discover peers with specific capabilities
`wallet_balance`	Check CLAW token balance and transactions
`apply_patch`	Apply unified diffs to files
`pdf_read`	Extract text from PDFs
`json`	Parse, query, and transform JSON
`echo` / `time`	Utility tools

Plus WASM sandbox tools and MCP server tools (stdio, server:tool_name format).

Agent Specs (TOML)

Define custom agents with model, tools, budget, and capabilities:

# my-agent.toml
[agent]
name = "code-reviewer"
description = "Reviews code for bugs and best practices"

[model]
name = "llama3.2:3b"
max_tokens = 4096
temperature = 0.3
system_prompt = "You are an expert code reviewer."

[capabilities]
storage = true

[budget]
per_request = 3.0
total = 500.0

[tools]
builtin = ["file_read", "file_list", "shell"]
allowed_commands = ["grep", "wc", "find", "cat"]

[channels]
websocket = true

peerclaw serve --web 127.0.0.1:8080 --ollama --agent my-agent.toml

Messaging Channels

Agents can receive and respond to messages across multiple platforms simultaneously. Configure channels in the [channels] section of your agent TOML, or via the dashboard under Workspace → Channels.

Telegram

Native integration via the Telegram Bot API (long polling).

1. Create a bot — Talk to @BotFather on Telegram and get your bot token.

2. Set the token — Add it to ~/.peerclaw/.env or export it:

export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

3. Configure your agent:

[channels]
telegram = { bot_token_env = "TELEGRAM_BOT_TOKEN" }

4. Run:

peerclaw serve --ollama --agent templates/agents/telegram-bot.toml

The bot will poll for messages and respond using your local LLM. See templates/agents/telegram-bot.toml for a complete example.

Webhook

HTTP endpoint that receives POST requests and responds with the agent's reply.

[channels]
webhook = true                  # Default port
webhook = { port = 8090 }      # Custom port

Send messages to the webhook:

curl -X POST http://localhost:8090/webhook \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!", "user_id": "u1", "conversation_id": "conv1"}'

Tip: Discord and Slack both support outgoing webhooks — you can connect them to PeerClaw's webhook channel without any adapter.

WebSocket

Used by the web dashboard chat. Enable it to allow real-time browser-based interaction:

[channels]
websocket = true

REPL

CLI stdin/stdout interaction. Useful for local testing:

[channels]
repl = true

Multiple channels

An agent can listen on several channels at once:

[channels]
repl = true
websocket = true
webhook = { port = 8090 }
telegram = { bot_token_env = "TELEGRAM_BOT_TOKEN" }

Dashboard configuration

You can also add channels at runtime from the web dashboard (Workspace → Channels) without editing TOML files. The dashboard supports Telegram (bot token), webhooks, and WebSocket.

Commands

Chat & Inference

peerclaw run <model>              # Interactive chat
peerclaw run <model> "prompt"     # Single query
peerclaw chat                     # Chat with slash commands (/help, /model, /tools, /status)

Models

peerclaw models list              # List downloaded models
peerclaw models download <model>  # Download from HuggingFace
peerclaw pull <model>             # Alias for download

Network

peerclaw serve                                # Start peer node
peerclaw serve --web 0.0.0.0:8080             # With web dashboard
peerclaw serve --ollama --share-inference     # Share LLM with network
peerclaw serve --ollama --agent agent.toml    # With agent runtime
peerclaw network status                       # Network health
peerclaw peers list                           # Connected peers

Vector Memory

peerclaw vector create <collection>              # Create collection
peerclaw vector insert <collection> <text>       # Insert with auto-embedding
peerclaw vector search <collection> <query> -k 5 # Semantic search

Skills, Tools, Wallet, Jobs

peerclaw skill list | install | search        # Skill management
peerclaw tool list | info | build             # Tool management
peerclaw wallet balance | send | history      # Token wallet
peerclaw job submit | status | list           # Job marketplace
peerclaw doctor                               # Run diagnostics

API

OpenAI-Compatible

peerclaw serve --web 127.0.0.1:8080

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/v1", api_key="unused")
response = client.chat.completions.create(
    model="llama-3.2-3b",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True
)
for chunk in response:
    print(chunk.choices[0].delta.content, end="")

Workflow API

Method	Path	Purpose
`POST`	`/api/workflows/validate`	Validate a workflow spec
`POST`	`/api/workflows/kickoff`	Start a workflow run
`GET`	`/api/workflows/runs`	List workflow runs
`GET`	`/api/workflows/runs/:id`	Run status and output
`GET`	`/api/workflows/runs/:id/stream`	SSE progress stream
`POST`	`/api/workflows/runs/:id/stop`	Cancel a run

Legacy aliases: /api/crews/* and /api/flows/*.

A2A Integration

Endpoint	Purpose
`GET /.well-known/agent-card.json`	Agent capabilities card
`POST /a2a`	JSON-RPC task interface
`GET /a2a/peers`	Discovered agent cards from the mesh

Python SDK

cd sdk/python && pip install -e ".[dev]"
export PEERCLAW_BASE_URL=http://127.0.0.1:8080
python examples/minimal.py

Architecture

peerclaw/
├── src/
│   ├── node.rs              # Orchestrates all subsystems
│   ├── agent/               # Agent runtime (ReAct loop, budget, tool execution)
│   ├── p2p/                 # libp2p networking (Kademlia, GossipSub, mDNS)
│   ├── inference/           # GGUF model loading, Ollama, remote API
│   ├── vector/              # vectX semantic search (HNSW, BM25, hybrid)
│   ├── job/                 # Request/bid/execute/settle workflow
│   ├── wallet/              # PCLAW token accounting, escrow
│   ├── tools/               # Builtin tools, WASM sandbox
│   ├── skills/              # SKILL.md prompt extensions
│   ├── safety/              # Leak detection, injection defense
│   ├── mcp/                 # Model Context Protocol client
│   ├── web/                 # Dashboard, OpenAI API, workflow API
│   └── messaging/           # Multi-platform channels
├── prompts/                 # Prompt templates (overridable at runtime)
├── templates/               # Agent, workflow, and skill templates
├── web/                     # React + Vite + shadcn dashboard
├── sdk/python/              # Python SDK
└── ironclaw/                # External tools and channel adapters

Key Dependencies

Subsystem	Crate
Async Runtime	`tokio`
P2P Networking	`libp2p` 0.54
Vector Database	`vectx`
WASM Sandbox	`wasmtime` 28.x
HTTP/Web	`axum` 0.7
Database	`redb` 2.x
Serialization	`serde` + `rmp-serde`
Crypto	`ed25519-dalek` 2.x, `blake3`
AI Inference	`llama-cpp-2` 0.1
CLI	`clap` 4.x

Prompt Customization

Override any prompt fragment without recompiling:

mkdir -p ~/.peerclaw/prompts
cp prompts/agentic_system_intro.txt ~/.peerclaw/prompts/
# Edit, then restart the node

Or set via environment or config:

export PEERCLAW_PROMPTS_DIR=/etc/peerclaw/prompts

Resolution order: [prompts].directory in config.toml → PEERCLAW_PROMPTS_DIR → ~/.peerclaw/prompts.

Configuration

Environment Variables

Variable	Description	Default
`PEERCLAW_HOME`	Base directory for data	`~/.peerclaw`
`PEERCLAW_LOG`	Log level (trace, debug, info, warn, error)	`info`
`PEERCLAW_PROMPTS_DIR`	Prompt fragment override directory	(unset)

Config File

Create ~/.peerclaw/config.toml:

[p2p]
listen_addresses = ["/ip4/0.0.0.0/tcp/0"]
bootstrap_peers = []
mdns_enabled = true

[web]
enabled = false
listen_addr = "127.0.0.1:8080"

[inference]
models_path = "~/.peerclaw/models"
default_model = "llama-3.2-3b"

[vector]
embedding_dim = 384
persistence_path = "~/.peerclaw/vector"

[safety]
leak_detection = true
injection_defense = true
policy_enforcement = true

Development

cargo build --release              # Build
cargo test                         # Run tests
cargo clippy                       # Lint
cargo fmt                          # Format

# Web UI development (hot reload)
cd web && npm install && npm run dev

# Production web build
cd web && npm run build

Testing Clusters

peerclaw test cluster --nodes 3           # Spawn test cluster
./scripts/run_agents.sh                   # 5 nodes with staggered startup

Roadmap

Completed

v0.2 — P2P networking, GGUF inference, job marketplace, token wallet, OpenAI API, web dashboard, vector memory, skills, safety, MCP
v0.3 — Swarm visualization, WASM sandbox, Ed25519 signatures, Rustyline CLI, diagnostics
v0.4 — Agent runtime (ReAct), LLM provider sharing, remote execution, tasks/providers dashboard, budget enforcement, crew orchestration, flows, A2A HTTP, Python SDK
v0.5 — Unified workflows, visual builder, agent library, multi-step templates, real-time WebSocket streaming, prompt customization

In Progress

Distributed inference (pipeline/tensor parallelism across peers)
Multi-agent hardening (production QA, load tests, CI fixtures)
Durable agent runs (checkpoint, resume, audit export)
Observability (structured traces, OTLP export)
Cross-peer tool execution with reputation signals
Human-in-the-loop (policy-gated pause/approve for high-risk actions)
Context compaction (LLM summarization for long sessions)

Future (v1.0)

On-chain settlement
Public tool registry
Governance
Firecracker microVM isolation

Security

WASM sandbox — Wasmtime with explicit capability grants
Noise protocol — End-to-end encryption for all P2P traffic
Ed25519 signatures — Cryptographic identity on all messages
Capability-based access — Explicit permission grants for tools and channels
Safety layer — Credential leak detection, prompt injection defense, content policy

License

PeerClaw is dual-licensed under:

MIT License (LICENSE-MIT)
Apache License 2.0 (LICENSE-APACHE)

Cargo version: 0.3.0 — README reflects the in-tree feature set through v0.5.

Name		Name	Last commit message	Last commit date
Latest commit History 136 Commits
docs		docs
prompts		prompts
scripts		scripts
sdk/python		sdk/python
src		src
templates		templates
tests		tests
web		web
.dockerignore		.dockerignore
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
README.md		README.md
build.rs		build.rs
docker-compose.yml		docker-compose.yml
test.txt		test.txt

Folders and files

Latest commit

History

Repository files navigation

PeerClaw

Overview

Key Features

Supported Backends

Inference

Messaging Channels

Screenshots

Chat — Agentic assistant with tool calling

Agent Builder — Visual workflow editor

Setup Wizard — Model downloads and configuration

Tools — Browse, inspect, and execute

P2P Network — Peer topology & connections

Settings — Inference backends

Skills — Template library

Quick Start

Docker (recommended)

Build from source

Download a model

Run

Web Dashboard

Built-in Agent Templates

Built-in Tools

Agent Specs (TOML)

Messaging Channels

Telegram

Webhook

WebSocket

REPL

Multiple channels

Dashboard configuration

Commands

Chat & Inference

Models

Network

Vector Memory

Skills, Tools, Wallet, Jobs

API

OpenAI-Compatible

Workflow API

A2A Integration

Python SDK

Architecture

Key Dependencies

Prompt Customization

Configuration

Environment Variables

Config File

Development

Testing Clusters

Roadmap

Completed

In Progress

Future (v1.0)

Security

License

About

Resources

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages