Generacy Onboarding Guide

Prerequisites

Before you begin, make sure you have the following installed:

• Docker Desktop (or Docker Engine on Linux)
• Node.js 22+ (for npx generacy)
• Git
• A GitHub account

Step 1: Sign Up on Generacy

1. Go to https://app.generacy.ai/
2. Click "Get Started"
3. Choose "Continue with GitHub" and authorize the Generacy app with your GitHub account

Step 2: Create a Project

1. From the Generacy dashboard, click "New Project"
2. Pick a name and select the GitHub repository you want to work on
3. Follow the prompt to install the Generacy GitHub App on the organization or account that owns the repository

Step 3: Launch the Cluster

On your new project page, click "Launch locally" to generate a launch command. Copy the command and run it in any terminal:

npx generacy@latest launch --claim=<code>

The CLI pulls the cluster image, starts Docker locally, and opens the in-browser bootstrap wizard. Claim codes expire 10 minutes after being generated — if yours expires, head back to the project page and click "Get a new command".

No manual API-key entry is needed: the wizard provisions Generacy and relay credentials for you.

Step 4: Complete the Bootstrap Wizard

Once the cluster connects, the bootstrap wizard walks you through three quick steps:

1. GitHub App install — grant the Generacy GitHub App access to the repositories you want the cluster to read and write.
2. Claude authentication — sign in with Claude Max via generacy claude-login, or paste an Anthropic API key. Either path works; Claude Max gives you the highest rate limits.
3. Peer-repo clone — if your project depends on sibling repositories (declared in .generacy/cluster.yaml), the wizard clones them into the cluster.

When the wizard reports Ready, the cluster is live and connected to the Generacy platform.

Step 5: Connect Your IDE

You have two ways to edit code in the cluster:

• In the browser — open the IDE tab on your project page to launch a code-server session in a new tab. Nothing else to install.
• Desktop VS Code via Remote Tunnel — open the Clusters tab, click "Connect with VS Code" , and complete the GitHub device-code flow. Your local VS Code then attaches to the cluster over the tunnel; you can also open the workspace from vscode.dev.

Step 6: Verify the Connection

1. Go back to your project on https://app.generacy.ai/dashboard
2. Open the Conversations tab
3. You should be able to communicate with Claude about your project
4. If the connection is working, you'll see activity from your cluster

Using Generacy for Development

Once your cluster is connected, Generacy works through GitHub issues and labels.

Creating Work Items

1. Go to your project's GitHub repository
2. Create a new Issue describing the feature or bug
3. Assign the issue to yourself
4. Apply one of the following labels to trigger a Generacy workflow:

The Workflow

1. Generacy picks up the issue — it detects the label and begins processing
2. Clarifying questions — Generacy may ask clarifying questions as comments on the issue. Respond to these to refine the requirements
3. Pull request — Once Generacy has enough context, it creates a PR with the implementation
4. Review and merge — Review the PR, request changes if needed, and merge when satisfied

Quick Reference