Developer docs / AI Fabric tutorials
OpenCode agents at scale
- Sandbox
- Batch / map
- Image DSL
Coding agents are embarrassingly parallel: a hundred bug-fix tasks don't need to wait for each other, they need a hundred isolated workspaces. That fits AI Fabric well: one sandbox per task, all launched at once with .map(). In this tutorial you'll fan out 20 agents (scale it to hundreds by changing one number), each cloning into its own throwaway container.
Before you start
You need the AI Fabric CLI installed and authenticated: run blade setup once. This is CPU-only and self-contained: it generates its own task list, so blade run works immediately.
Build the agent image
Each agent needs git and a Node toolchain (most coding-agent CLIs are Node-based). Build one image and reuse it for every sandbox:
import bladekit
app = bladekit.app("opencode-agents")
agent_image = (
bladekit.Image.debian_slim(python_version="3.12")
.apt_install("git", "nodejs", "npm")
.pip_install("httpx")
)One agent, one sandbox
The worker function takes a task, opens a sandbox, optionally clones a repo, drops the prompt in, and runs the agent. Here the agent step is a placeholder ls so the tutorial runs anywhere. Swap in your real CLI (OpenCode, Aider, …) where the comment says:
@app.function(timeout=300)
def run_coding_agent(task: dict) -> dict:
"""Run one coding agent in an isolated sandbox."""
task_id = task["id"]
prompt = task["prompt"]
repo_url = task.get("repo_url", "")
with bladekit.Sandbox.create(image=agent_image, timeout=240) as sb:
if repo_url:
proc = sb.exec("git", "clone", repo_url, "/work/repo")
proc.wait()
sb.write_file("/work/task.txt", prompt.encode())
# In practice, invoke your coding agent CLI here.
proc = sb.exec("ls", "-la", "/work/")
proc.wait()
output = proc.stdout.read().decode()
return {"task_id": task_id, "status": "done", "output": output[:500]} Fan out with .map()
Build a list of tasks and hand it to run_coding_agent.map(...). AI Fabric schedules them across the fleet in parallel, and 20 sandboxes spin up at once. return_exceptions=True keeps one crashed agent from sinking the whole batch:
@app.local_entrypoint()
def main():
tasks = [
{"id": f"task-{i}", "prompt": f"Fix bug #{i} in the codebase", "repo_url": ""}
for i in range(20)
]
results = list(run_coding_agent.map(tasks, return_exceptions=True))
done = sum(1 for r in results if not isinstance(r, Exception))
print(f"{done}/{len(tasks)} agents completed")Run it
blade run opencode_agents.pyYou'll see 20/20 agents completed. To scale up, bump the range(20). Each task still gets its own isolated sandbox, and AI Fabric handles the scheduling.
Take it for a spin
Everything above in one file, ready to run.
import bladekit
app = bladekit.app("opencode-agents")
agent_image = (
bladekit.Image.debian_slim(python_version="3.12")
.apt_install("git", "nodejs", "npm")
.pip_install("httpx")
)
@app.function(timeout=300)
def run_coding_agent(task: dict) -> dict:
"""Run one coding agent in an isolated sandbox."""
task_id = task["id"]
prompt = task["prompt"]
repo_url = task.get("repo_url", "")
with bladekit.Sandbox.create(image=agent_image, timeout=240) as sb:
# Clone repo if provided
if repo_url:
proc = sb.exec("git", "clone", repo_url, "/work/repo")
proc.wait()
# Write the task prompt
sb.write_file("/work/task.txt", prompt.encode())
# In practice, invoke your coding agent CLI here.
# This example just lists the repo contents.
proc = sb.exec("ls", "-la", "/work/")
proc.wait()
output = proc.stdout.read().decode()
return {"task_id": task_id, "status": "done", "output": output[:500]}
@app.local_entrypoint()
def main():
tasks = [
{"id": f"task-{i}", "prompt": f"Fix bug #{i} in the codebase", "repo_url": ""}
for i in range(20)
]
results = list(run_coding_agent.map(tasks, return_exceptions=True))
done = sum(1 for r in results if not isinstance(r, Exception))
print(f"{done}/{len(tasks)} agents completed")Concepts used: Cold start, Run