Ludus

Ludus Magnus is the multi-agent software arena — it defines agents, their behavior, and how they are deployed. The name comes from the Ludus Magnus, the great training school adjacent to the Roman Colosseum.

What Ludus Manages

Concern	How
Agent definitions	SOUL.md + ROLE.yaml per agent
Sandbox containers	Docker images with per-agent resource limits
Deployment	just deploy rsyncs agents, scripts, and skills to ludus hosts
Work routing	Tier 1 (zero-token) label-based routing via the Beads watcher
Agent wake-up	The watcher polls bd ready, groups by label, wakes the right agent

Architecture

Ludus follows a Four-Tier Execution Framework that classifies every operation by its reasoning requirement:

Tier	Description	Token Cost
1 — System Cron	Deterministic scripts (polling, routing)	Zero
2 — LLM Cron	Tasks requiring interpretation	Isolated
3 — Heartbeat	Multiple lightweight checks sharing context	Shared
4 — Pull Heartbeat	Agent self-serves from work queues	Full reasoning

The key insight: tokens are compute budget. Every token spent on a task that doesn't require reasoning is wasted. The watcher (Tier 1) routes work without consuming any LLM tokens.

Sandbox Containers

All agents run in Docker containers with per-agent configuration:

fedora:43
  ├─► openclaw-sandbox:fedora        ← Minimal: bash, curl, git, python3
  ├─► openclaw-sandbox-common:fedora ← + Node.js, npm, gcc, make
  ├─► b4arena-base:latest            ← + gh, bd CLI
  └─► b4arena-dev:latest             ← + full dev toolchain

Containers are reused if config matches, recreated on config change, and pruned after 24h idle.

Key Commands

just deploy-agents       # Rsync agents/scripts/skills to hosts
just deploy-full         # First-time: full sync + images + register + configure
just status              # Show registered agents + sync state
just images-build        # Build sandbox Docker images

Source: ludus/docs/architecture.md — full architecture with all design decisions.