Getting started

For AI coding tools

AI, this one's for you. Sections tagged like this are written for the coding tool driving this setup, not the human reading along. Treat them as operating instructions:

Run each kradle command yourself. Don't just print it for the user to copy.
Exception: the CLI installer in Step 1. If kradle already resolves, skip it. If not, run the installer yourself and then export PATH="$HOME/.kradle/bin:$PATH" for your session. The installer runs in a child process and cannot change your shell's PATH.
Surface errors immediately instead of continuing past them.
kradle init triggers an interactive browser sign-in by default. If the user is on a headless box pass --skip-auth instead; if they handed you an existing API key pass --api-key <key>.
Never commit the API key. The recommended kradle login flow saves it to ~/.kradle/config.json (outside the repo). If you write it to .env, make sure .env is in .gitignore.
When you need authoritative reference material, run kradle ai-docs. It lists subcommands for CLI flags, the challenge authoring SDK, and more. Pull what you need from there.

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.

Prerequisites

1. Kradle account

Sign up at kradle.ai and click Login in the upper-right corner. In Step 1 you'll sign the CLI in from your browser, which mints an API key for you automatically.

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.

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

Restart your terminal after installation!

Hey, save yourself the scroll. Point your favorite AI coding tool (Claude Code, Cursor, Codex, etc.) at this page and let it walk you through the rest. It'll read the guide, run the commands, and have you shipping a challenge faster than you can finish your coffee.

Copy this and paste it into the tool to get started:

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

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.

AI tip

If kradle is not found after installation, do not reinstall. Add the install directory to PATH for this session: export PATH="$HOME/.kradle/bin:$PATH" (PowerShell: $env:Path = "$env:USERPROFILE\.kradle\bin;$env:Path").
When kradle init asks how to authenticate, Sign in via browser is the default and the right pick unless the user said otherwise. A browser tab will open for them; just wait for it to finish.
If running fully unattended (no human, no browser), use kradle init --skip-auth and tell the user to run kradle login later.
If the user explicitly provided an existing API key, pass it as kradle init --api-key <key> to skip the prompt.
After kradle init finishes, reading the generated AGENTS.md file is mandatory before you do anything else.

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:

File	Purpose
`challenges/my-first-challenge/challenge.ts`	Game logic. What happens in Minecraft: variables, scoring, spawning, items, time limits, win conditions. Compiles to a datapack.
`challenges/my-first-challenge/config.ts`	Metadata. What agents are told (task description, roles, participant counts) and how results are scored.

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.

AI tip

Before touching challenge.ts or config.ts: run kradle ai-docs challenges-sdk and read the output. It's the authoritative reference for the TypeScript SDK. Don't guess at APIs from what you remember. When the user's description leaves gaps (time limit, participant counts), pick sensible defaults (e.g. 2-minute time limit, single role if unclear, …) and surface each default so they can correct it.

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:

Compiles challenge.ts into a Minecraft datapack
Validates all generated commands for syntax errors
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

AI warning

Don't start kradle challenge watch during this walkthrough. It's long-running and will occupy the terminal, blocking the rest of the guide. Only invoke it if the user explicitly asks for watch mode. For the one-shot build that Step 4 needs, stick with kradle challenge build my-first-challenge. If the build reports TypeScript or datapack validation errors, fix them before moving on. Don't hide them from the user.

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.