Druids

Druids is a batteries-included library to coordinate and deploy coding agents across machines. You write Python functions that specify agents, their goals, and how they talk to each other. Druids runs the infrastructure.

You can use it locally or deployed on druids.dev.

Website · Docs · Getting started · Discord

Agent software

A program is an async function. You create agents, define events they can trigger, and control what happens when they do. The agent decides when to trigger an event — the program decides what happens.

async def program(ctx):
    # Create a profiler agent on a remote VM
    profiler = await ctx.agent(
        "profiler",
        prompt="Profile the app. Find the slowest functions.",
    )

    results = {}

    # The profiler calls this event for each bottleneck it finds
    @profiler.on("found_bottleneck")
    async def on_bottleneck(name="", analysis=""):
        opt = await ctx.agent(
            f"opt-{len(results) + 1}",
            prompt=f"Optimize: {name}\n\n{analysis}",
        )

        # Each optimizer calls this when it's done
        @opt.on("submit")
        async def on_submit(speedup=""):
            results[name] = speedup

    # The profiler calls this when it's finished profiling
    @profiler.on("all_done")
    async def on_done():
        await ctx.done(results)

Events are how agents modify state in a controlled way. Use them when the program needs to do something the agent can't — creating other agents, enforcing retry limits, recording results, signaling completion. Everything the agent can do itself (reading files, running commands, editing code) stays with the agent.

Primitives

ctx.agent()	Create an agent on a sandboxed VM
@agent.on()	Define events the agent can trigger
agent.fork()	Copy-on-write clone of a VM (hosted only)
ctx.connect()	Let agents message and send files
share_machine_with	Put multiple agents on the same VM
await ctx.done()	Complete the execution

Each agent gets a sandboxed VM with your repo and dependencies. Agents can share machines, transfer files, and work on git branches. On the hosted version, agent.fork() creates instant copy-on-write clones. You can message any agent while it runs, inspect program state, and redirect work without stopping the execution.

Quickstart

You need Docker, uv, and an Anthropic API key.

bash scripts/setup.sh

This builds the Docker image, starts the server, and configures the CLI. Then run a program:

druids exec .druids/build.py spec="Add a /health endpoint that returns 200 OK"

See the getting started guide for a full walkthrough, or QUICKSTART.md for manual setup and troubleshooting.

Example programs

• build.py — builder + critic + auditor. Three agents iterating until all are satisfied.
• basher.py — finder scans for tasks, spawns implementor+reviewer pairs.
• review.py — demo agent tests a PR on a real system, monitor watches for shortcuts.
• main.py — Claude and Codex racing on the same spec in parallel.

Architecture

• server/ — FastAPI server, execution engine, sandbox management
• client/ — CLI and Python client library
• runtime/ — program runtime SDK
• frontend/ — Vue 3 dashboard
• docs/ — documentation (also served at druids.dev/docs)