Dev Setup

Set up a local development environment for #B4arena from scratch.

Goal

A working meta/ workspace with all sub-repos cloned, tools installed, and the ability to run agents locally.

Prerequisites

• Git with SSH access to the b4arena GitHub organization
• Node.js ≥ 20.0 (for Tabula and frontend projects)
• Python ≥ 3.11 with uv (for Ludus CLI)
• just — command runner (installation)
• gh — GitHub CLI, authenticated (gh auth login)

Steps

1. Clone the workspace

git clone git@github.com:b4arena/meta.git
cd meta

2. Set up all sub-repos

just setup

This clones all organization repos as subtrees under meta/:

meta/
├── arena/          ← org design docs
├── ludus/          ← agent config & deployment
├── infra/          ← Ansible deployment
├── observe/        ← observability hub
├── tabula/         ← this knowledge base
├── exploration-openclaw/
└── resources/      ← external reference checkouts

Expected output: Each repo is cloned. No errors.

3. Install the Ludus CLI

cd ludus
uv sync

Verify:

uv run ludus --help

Expected output: Ludus CLI help text with available commands.

4. Install the Beads CLI (bd)

The bd CLI is a Go binary. Install from the Beads releases:

# Linux amd64
curl -L https://github.com/steveyegge/beads/releases/latest/download/bd-linux-amd64 -o /usr/local/bin/bd
chmod +x /usr/local/bin/bd

For ARM64 (e.g., Raspberry Pi):

curl -L https://github.com/steveyegge/beads/releases/latest/download/bd-linux-arm64 -o /usr/local/bin/bd
chmod +x /usr/local/bin/bd

Verify:

bd --version

5. Initialize Beads in a project

cd /path/to/your/project
bd init --prefix myproj

Expected output: .beads/ directory created with a Dolt database.

6. Set up Tabula locally (optional)

cd meta/tabula
npm install
npm start

Expected output: Docusaurus dev server at http://localhost:3000/.

Validation

Run these checks to confirm everything is working:

# All repos present
ls meta/arena meta/ludus meta/infra meta/tabula

# Ludus CLI works
cd meta/ludus && uv run ludus --help

# Beads CLI works
bd --version

# Git access works
gh repo list b4arena --limit 5

If Things Go Wrong

Problem	Solution
just setup fails on a repo	Check SSH keys: ssh -T git@github.com. Ensure you have access to the b4arena org.
uv sync fails	Ensure Python ≥ 3.11: python3 --version. Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
bd init fails	Ensure Dolt is installed: dolt version. Install from dolthub/dolt releases.
npm install fails in tabula	Ensure Node.js ≥ 20: node --version.
gh auth issues	Run gh auth login and select SSH protocol.