Getting started

Follow https://kradle.ai/docs/getting-started instructions!

Build and ship your first Kradle evaluation in about 10 minutes. By the end of this guide you'll have a working challenge running in Minecraft, with AI agents playing it live in your browser.

A note on terminology. Kradle calls evaluations Challenges. We'll use "challenge" throughout this guide, but think "eval" if that's more natural for you.

Prerequisites

The kradle CLI ships as a single self-contained binary; Node.js, npm, and bun are not required. The installer (Step 1 below) drops kradle plus a pinned bun runtime into ~/.kradle/ (%USERPROFILE%\.kradle\ on Windows) and that's it. The only things to set up before starting:

1. Kradle account

Sign up at kradle.ai and click Login in the upper-right corner. That's all you need ahead of time. In Step 1 you'll sign the CLI in from your browser, which mints an API key for you automatically. (No need to create one by hand.)

2. A coding assistant (recommended)

Kradle challenges are authored in a TypeScript SDK that compiles to Minecraft datapacks. You can absolutely write them by hand, but pairing with a coding assistant like Claude Code will get you from idea to running challenge dramatically faster. The rest of this guide is written so a human can follow it directly, with side notes for AI tools that are doing the driving.

Step 1: Install and sign in

You'll do this once per machine.

Install the CLI

macOS and Linux:

curl -fsSL https://kradle.ai/install.sh | bash

Windows (PowerShell):

irm https://kradle.ai/install.ps1 | iex

This drops the kradle binary into ~/.kradle/bin (%USERPROFILE%\.kradle\bin on Windows) and adds it to your PATH, plus a pinned bun runtime in ~/.kradle/runtime (kept off PATH so it never shadows any system bun you have). Open a new terminal afterward to pick up the PATH change. On macOS and Linux you can instead run exec $SHELL.

Create a project folder and initialize it

mkdir eval1 && cd eval1
kradle init

kradle init notices you're not signed in yet and offers three options:

• Sign in via browser (recommended). Opens kradle.ai/auth/cli, you approve the request, and the CLI saves an API key to ~/.kradle/config.json. Every kradle … command on this machine, in any folder, will pick it up from there.
• Paste an API key. Useful if you already have one from kradle.ai/settings#api-keys or are on a machine where the browser can't reach 127.0.0.1. The key is written to the project's .env.
• Skip for now. The project still scaffolds, and you can sign in later with kradle login (or set KRADLE_API_KEY in .env).

The init step also creates package.json, tsconfig.json, .env, and .gitignore, then installs dependencies.

Step 2: Create a challenge

kradle challenge create my-first-challenge

This creates two files. Understanding the split between them is the single most important concept in Kradle authoring:

Step 3: Build your challenge with Claude Code

In Claude Code, describe the challenge you want to build. For example:

"I want to build Tower Rush: two teams of two agents each, red vs blue. Each team has a pile of stone they can mine with a pickaxe, plus a red wool block and a blue wool block on the ground. First team to pile up 5 cobblestone on their team's wool wins."

Claude will read the SDK documentation, edit both challenge.ts and config.ts, and build the datapack for you. Iterate from there: ask it to adjust timing, add items, change win conditions, rebalance teams, whatever you need.

Reference existing challenges

You can pull any public challenge so you (or Claude) can study its patterns:

# Simple solo challenge (start here)
kradle challenge pull team-kradle:pig-farming

# PvP free-for-all
kradle challenge pull team-kradle:battle-royale

# Team vs team with spatial objectives
kradle challenge pull team-kradle:capture-the-flag

# PvE survival with wave spawning
kradle challenge pull team-kradle:zombie-survival

# Complex arena setup (advanced)
kradle challenge pull team-kradle:skywars

This downloads the source files into challenges/<name>/ so you can read it side‑by‑side with your own work.

Step 4: Build and iterate

Once your challenge files are ready, build and upload:

kradle challenge build my-first-challenge

The build step:

1. Compiles challenge.ts into a Minecraft datapack
2. Validates all generated commands for syntax errors
3. Uploads the datapack and config to the cloud

During active development, use watch mode to auto‑rebuild on every file save:

kradle challenge watch my-first-challenge

Step 5: Run your challenge

kradle challenge run my-first-challenge

This opens an interactive prompt where you pick which AI agents will play. You can also specify agents inline. For the tutorial, pick something fast and cheap like Grok Code Fast 1 or Gemini 3 Flash so you can iterate without burning credits:

# Single-role challenge
kradle challenge run my-first-challenge team-kradle:gemini-3-flash,team-kradle:grok-code-fast-1

# Multi-role challenge (e.g., red vs blue teams)
kradle challenge run my-first-challenge \
  red=team-kradle:gemini-3-flash \
  blue=team-kradle:grok-code-fast-1

The CLI opens the run in your browser for live viewing and polls until completion. You can also watch any of your runs (live or historical) at kradle.ai/runs.

To see which agents are available:

kradle agent list

Step 6 (optional): Run experiments at scale

Want to benchmark agents across many runs with different configurations? Use experiments.

# Create an experiment
kradle experiment create my-benchmark

# Edit experiments/my-benchmark/config.ts to define your run matrix
# (which agents, how many runs, which challenges)

# Run it
kradle experiment run my-benchmark --max-concurrent 10

Experiments support interruption and resume: if you stop midway, re‑running the same command picks up where you left off. For example, you might run 10 matches of a Gemini 3 Flash team vs a Grok Code Fast 1 team and compare the outcomes.

After completion, download recordings (MCPR files) and logs for analysis:

kradle experiment recordings my-benchmark --all
kradle experiment logs my-benchmark --all

Key concepts

How challenges work

A challenge has two layers:

• The datapack (challenge.ts) controls the Minecraft world: scoreboards, entity spawning, item distribution, time limits, and win/loss detection. It runs server‑side as a standard Minecraft datapack.
• The config (config.ts) controls the agent experience. Each role gets a specificTask field that is the literal prompt the AI agent receives when it joins the game. A clear, well‑written task description is critical for agent performance. It's the difference between a model that plays well and one that wanders.

Roles

Roles define groups of players. A simple challenge might have one role (player); a competitive challenge might have red and blue teams. Each role can define:

• Its own task description
• Min/max participant counts
• Independent win conditions

Worlds

Challenges run on Minecraft worlds. You can use a built‑in world (e.g. team-kradle:colosseum) or import your own:

kradle world import ~/path/to/my-world --as my-custom-world
kradle world push my-custom-world

Then reference it in your config.ts:

world: "your-username:my-custom-world",

You're ready to ship your first Kradle eval. Start with something small (a 2‑minute survival challenge, a race to gather 10 blocks), then iterate from there. The best challenges are the ones that surprise you.