yaarbal 0.1.1

BitTorrent-inspired peer-to-peer distributed LLM inference

Yaarbal

Yaarbal — the open model library. Contribute compute, access every model.

⚠ Status: early prototype. The credit economy and trust system are demo-grade; do not run production workloads on the public network.

Visit yaarbal.app for the demo network.

Quickstart

pip install yaarbal && yaarbal run qwen2.5-0.5b-instruct "hello"

The single command above installs yaarbal from PyPI and runs a one-shot inference against a small (~600 MB) Qwen 2.5 0.5B instruct model. By default it auto-discovers any seeders on your local network or the configured tracker, submits the prompt, and streams tokens back to your terminal. If no seeder is reachable, the command exits with a clear error pointing at yaarbal seed (see Usage below).

Installation

From PyPI (recommended)

pip install yaarbal
yaarbal --version

See docs/distribution/INSTALL.md for Homebrew + Docker install paths and troubleshooting.

Alternate: install from source

git clone https://github.com/<owner>/yaarbal
cd yaarbal
pip install -e .

Requirements

• Python 3.11 or newer
• macOS or Linux (Windows is untested)
• (Optional) A Hugging Face token in HF_TOKEN for gated models such as Llama 3.1 8B and above

The shipped CLI works on a CPU-only laptop for small models (Qwen 0.5B, Phi-3-mini Q4_K_M, MiniGPT). GPU acceleration (CUDA / Apple MPS) is auto-detected when available; pass --device cpu to force CPU.

Usage

yaarbal is a single binary with five subcommands. Run yaarbal --help for the full list.

Run inference (one-shot)

yaarbal run qwen2.5-0.5b-instruct "your prompt here"

Streams tokens to stdout. Falls back to a non-streaming pull-mode if the seeder does not advertise SSE support. Configuration precedence: explicit flags > YAARBAL_* environment variables > ~/.yaarbal/config.toml > built-in defaults.

Host a seeder (contribute compute)

yaarbal seed --model qwen2.5-0.5b-instruct

Loads the named model end-to-end, registers with the configured tracker, and serves /inference, /inference/stream, /v1/chat/completions, and /v1/models over HTTP. Seeders earn credits on every settled inference and spend them when running yaarbal run against the network.

Interactive chat

yaarbal chat --model qwen2.5-0.5b-instruct

Multi-turn REPL with rolling conversation history. In-REPL commands: /models, /health, /metrics, /reset, /quit. Honors YAARBAL_CHAT_BACKEND=single + YAARBAL_SINGLE_NODE_URL when you want to talk to a local seeder without a tracker.

Other subcommands

Command	Effect
yaarbal status	Credit balance, hosted models, tracker peer count (plain-text by default; --json for scripting)
yaarbal tracker [PORT]	Run a tracker for a self-hosted Yaarbal network (default port 8000)
yaarbal ui	Serve the local browser chat UI on 127.0.0.1:5173 (auto-opens in your browser; --no-open to suppress)
yaarbal --version	Print the installed package version
yaarbal --help	Full subcommand list

Optional swarm authentication

Set YAARBAL_AUTH_USER and YAARBAL_AUTH_PASS in the environment before starting tracker, seeders, and leechers so all HTTP traffic uses HTTP Basic Auth. If unset, authentication is disabled (typical for local dev). HTTP Basic is not a substitute for TLS — see KNOWN_LIMITATIONS.md.

For Engineers

For the engineering deep-dive — architecture, protocol design, model registry, BitTorrent-inspired piece-wise inference, credit economy mechanics — see PROJECT_OVERVIEW.md.

For the issue tracker (open limitations, P0–P3 prioritized), see KNOWN_LIMITATIONS.md.

For deeper component documentation:

• docs/architecture/ — protocol design and architectural notes
• docs/deployment/ — Docker / multi-node deployment
• docs/guides/ — getting started, development, contributing
• docs/testing/ — test plan and manual testing guide
• docs/api/reference.md — HTTP endpoint reference
• bittorrent/README.md — internal docs for the inference-routing component
• MODELS.md — full model catalog (30+ entries) with hardware requirements
• QUICKSTART.md — alternate single-node walkthrough and Docker (Compose) profile reference

Run with Docker (Compose)

The repo ships role-separated services (tracker, seeder, leecher, chat-proxy) in docker-compose.yml. The fastest container path is the single-node profile, which mirrors the local quickstart:

docker compose --profile single-node up single-node
# from a second terminal:
YAARBAL_CHAT_BACKEND=single YAARBAL_SINGLE_NODE_URL=http://127.0.0.1:7001 \
  yaarbal chat --model qwen2.5-0.5b-instruct

Other available profiles: default, convenience, query, web. See QUICKSTART.md for the full profile / port matrix.

Testing

The project ships a pytest-managed test suite under tests/ covering unit, integration, regression, and large-scale tiers.

pip install -e .
make test                # full suite
make test-unit           # unit tier only
make test-integration    # integration tier only
make test-verbose        # full suite with verbose output
python -m pytest tests/unit/test_tracker.py -v   # one file

CI runs on every push and PR via .github/workflows/python-ci.yml (Python 3.10 syntax check) and .github/workflows/pr-regression.yml (full unittest on PRs into main).

Contributing

Pull requests are welcome.

1. Fork the repository and create a feature branch.
2. Match the existing style — Python type hints + docstrings throughout; conventional-commit messages on commits.
3. Add or update tests under tests/unit/ or tests/integration/ for any new behavior.
4. Run make test to confirm a green suite before opening a PR.
5. Open a PR against main with a short description of the change and a link to any tracking issue.

Issues, feature requests, and protocol-design discussion: file an issue on github.com//yaarbal. For deeper protocol questions, the research artifacts under docs/research/ are a good starting point.

Further reading

Yaarbal originated as research on P2P inference — see docs/research/ for the original protocol design and rebuttal exchange.

License

Copyright 2026 Abdul Hannan Kanji. Licensed under Apache-2.0.