Getting Started: Your First AI Agent in 5 Minutes

This guide walks you through setting up ClusterCode from scratch. By the end, you will have an AI agent working on a real GitHub issue in an isolated DevBox on your own machine.

Prerequisites: You need Node.js 20+, Podman installed, and a GitHub account. You will also need an Anthropic API key for Claude Code (the default agent).

Step 1: Install the orchestrator. Clone the ClusterCode repository and run npm install in the apps/orchestrator directory. Copy .env.example to .env and fill in your configuration. Run npm run dev to start the dashboard.

Step 2: Register a worker. In a separate terminal, navigate to apps/worker-agent. Copy .env.example to .env and set your ORCHESTRATOR_WS_URL to point to your running orchestrator. Run npm start. The worker will connect via WebSocket and appear in your dashboard.

Step 3: Create your first DevBox. Open the dashboard, click "New DevBox", and paste a GitHub issue URL. Select your worker and agent (Claude Code, OpenAI Codex, or GitHub Copilot — each uses your own API key). Click "Launch". The orchestrator will instruct your worker to spin up a DevBox with the repository cloned, dependencies installed, and the AI agent running.

Step 4: Watch it work. The dashboard shows real-time logs and a live web terminal for the DevBox. You can see the agent reading the issue, exploring the codebase, writing code, and running tests. When it is done, it creates a pull request.

Step 5: Review the PR. The agent's pull request appears in your GitHub repository like any other PR. Review it, request changes, or merge it. The DevBox is automatically cleaned up.

That is it. You now have a self-hosted AI coding pipeline. Scale it by adding more workers, or run multiple DevBoxes in parallel on the same worker. From here you can group repos into Projects, set up cron Schedules, or launch on-demand Runs that pause to ask you a question and resume on your answer.