kradle 0.6.7 → 0.6.8

package/README.md

@@ -177,6 +177,39 @@ When no agents are specified, the command enters interactive mode, fetching the
 
 By default, the command opens the run URL in your browser and polls until the run completes, then displays the outcome.
 
+### Run Challenge Locally
+
+Run a challenge locally using Docker (requires Docker Desktop):
+
+```bash
+# Run locally with inline agents
+kradle challenge run <challenge-name> --local team-kradle:gemini-3-flash,team-kradle:grok-4-1-fast
+
+# Run locally with interactive agent selection
+kradle challenge run <challenge-name> --local
+
+# Use a dev/staging arena image instead of production
+kradle challenge run <challenge-name> --local \
+  --arena-image us-central1-docker.pkg.dev/mckradle-3c267/dev-arenas/minecraft:abc1234
+```
+
+The `--local` flag spins up a Minecraft server and arena-minecraft as Docker containers on your machine. This is useful for testing challenges during development without going through the cloud backend.
+
+**Requirements:**
+- Docker Desktop must be running
+- First run will pull container images (may take a few minutes)
+- The challenge must exist locally (with `challenge.ts` and `config.ts`)
+
+**What happens:**
+1. Builds the challenge datapack locally
+2. Downloads the world from the cloud
+3. Starts a Minecraft server container (port 25565)
+4. Starts an arena-minecraft container
+5. Streams arena logs to your terminal
+6. Press Ctrl+C for graceful shutdown
+
+**Arena Image Override:** By default, the production arena image is used. Set `--arena-image` or the `KRADLE_ARENA_IMAGE` environment variable to test dev or staging builds.
+
 ### List Runs
 
 List your recent runs:
@@ -508,6 +541,8 @@ kradle-cli/
 │   │   │   └── runs/         # Run listing and logs commands
 │   │   ├── experiment/       # Experiment commands
 │   │   └── world/            # World management commands
+│   ├── config/
+│   │   └── releases/         # Release tags (updated by CI)
 │   └── lib/                  # Core libraries
 │       └── experiment/       # Experiment system
 ├── tests/                    # Integration tests

package/dist/commands/challenge/run.d.ts

@@ -12,8 +12,11 @@ export default class Run extends Command {
         "web-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         "studio-api-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         "studio-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "challenges-path": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         studio: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         record: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "arena-image": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         "no-open": import("@oclif/core/interfaces").BooleanFlag<boolean>;
         "no-wait": import("@oclif/core/interfaces").BooleanFlag<boolean>;
         "no-summary": import("@oclif/core/interfaces").BooleanFlag<boolean>;
@@ -34,5 +37,9 @@ export default class Run extends Command {
      * Fetches challenge config from cloud and prompts user to select agents for each role.
      */
     private selectAgentsInteractively;
+    /**
+     * Run a challenge locally using Docker (MC server + arena-minecraft).
+     */
+    private runLocally;
     run(): Promise<void>;
 }

package/dist/commands/challenge/run.js

@@ -2,7 +2,8 @@ import { Command, Flags } from "@oclif/core";
 import enquirer from "enquirer";
 import pc from "picocolors";
 import { ApiClient } from "../../lib/api-client.js";
-import { getChallengeSlugArgument } from "../../lib/arguments.js";
+import { extractShortSlug, getChallengeSlugArgument } from "../../lib/arguments.js";
+import { Challenge } from "../../lib/challenge.js";
 import { getConfigFlags } from "../../lib/flags.js";
 import { clearScreen, formatDuration, fuzzyHighlight, getRunStatusDisplay, openInBrowser } from "../../lib/utils.js";
 const POLL_INTERVAL_MS = 2000;
@@ -21,6 +22,9 @@ export default class Run extends Command {
         "<%= config.bin %> <%= command.id %> my-challenge --no-wait",
         "<%= config.bin %> <%= command.id %> my-challenge team-kradle:gemini-3-flash,team-kradle:grok-4-1-fast",
         "<%= config.bin %> <%= command.id %> capture-the-flag red=team-kradle:gemini-3-flash blue=team-kradle:grok-4-1-fast",
+        "<%= config.bin %> <%= command.id %> my-challenge --local",
+        "<%= config.bin %> <%= command.id %> my-challenge --local team-kradle:gemini-3-flash,team-kradle:grok-4-1-fast",
+        "<%= config.bin %> <%= command.id %> my-challenge --local --arena-image us-central1-docker.pkg.dev/mckradle-3c267/dev-arenas/minecraft:abc1234",
     ];
     static args = {
         challengeSlug: getChallengeSlugArgument({
@@ -30,6 +34,15 @@ export default class Run extends Command {
     static flags = {
         studio: Flags.boolean({ char: "s", description: "Run in studio environment", default: false }),
         record: Flags.boolean({ char: "r", description: "Record the run (enables video recording)", default: false }),
+        local: Flags.boolean({
+            char: "l",
+            description: "Run the challenge locally using Docker (spins up MC server + arena-minecraft)",
+            default: false,
+        }),
+        "arena-image": Flags.string({
+            description: "Override arena-minecraft Docker image URL (for testing dev/staging builds)",
+            env: "KRADLE_ARENA_IMAGE",
+        }),
         "no-open": Flags.boolean({
             description: "Don't open the run URL in the browser",
             default: false,
@@ -46,7 +59,7 @@ export default class Run extends Command {
             description: "Open the run URL with screenshots mode enabled",
             default: false,
         }),
-        ...getConfigFlags("api-key", "api-url", "web-url", "studio-url", "studio-api-url"),
+        ...getConfigFlags("api-key", "api-url", "web-url", "studio-url", "studio-api-url", "challenges-path"),
     };
     async pollForCompletion(api, runId, waitForSummary) {
         let lastStatus = "";
@@ -256,13 +269,108 @@ export default class Run extends Command {
         }
         return participants;
     }
+    /**
+     * Run a challenge locally using Docker (MC server + arena-minecraft).
+     */
+    async runLocally(challengeSlug, 
+    // biome-ignore lint/suspicious/noExplicitAny: oclif flag types are complex
+    flags, agentArgs) {
+        // Validate incompatible flags
+        const incompatible = ["studio", "no-open", "no-wait", "screenshots", "record"];
+        for (const flag of incompatible) {
+            if (flags[flag]) {
+                this.error(`--${flag} is not compatible with --local`);
+            }
+        }
+        const apiUrl = flags["api-url"];
+        const api = new ApiClient(apiUrl, flags["api-key"]);
+        // Parse participants
+        let participants;
+        if (agentArgs.length > 0) {
+            participants = this.parseInlineAgents(agentArgs);
+        }
+        else {
+            this.log(pc.blue(">> Fetching challenge configuration..."));
+            const [challenge, availableAgents] = await Promise.all([api.getChallenge(challengeSlug), api.listKradleAgents()]);
+            this.log(pc.dim(`Challenge: ${challenge.name}`));
+            this.log(pc.dim(`Roles: ${Object.keys(challenge.roles).join(", ")}`));
+            this.log("");
+            participants = await this.selectAgentsInteractively(challenge, availableAgents);
+        }
+        if (participants.length === 0) {
+            this.error("No participants specified. Use inline syntax or select agents interactively.");
+        }
+        // Fetch challenge data from API
+        this.log(pc.blue(">> Fetching challenge configuration..."));
+        const challengeData = await api.getChallenge(challengeSlug);
+        // Build datapack locally
+        this.log(pc.blue(">> Building challenge datapack..."));
+        const shortSlug = extractShortSlug(challengeSlug);
+        const challenge = new Challenge(shortSlug, flags["challenges-path"]);
+        const { config } = await challenge.buildLocal({ validate: true });
+        // Create a real job in the backend (env: "studio" skips remote arena creation)
+        // Get the FULL raw response — it's passed directly to the arena (same as Studio)
+        this.log(pc.blue(">> Creating run in backend..."));
+        const jobPayload = await api.runChallengeRaw({
+            challenge: challengeSlug,
+            participants,
+            jobType: "foreground",
+            env: "studio",
+        });
+        const jobId = jobPayload.id;
+        const runIds = jobPayload.runIds;
+        if (!jobId || !runIds?.length) {
+            this.error("Backend did not return job ID or run IDs. Check your API key and challenge slug.");
+        }
+        const runId = runIds[0];
+        this.log(pc.dim(`Job: ${jobId}`));
+        this.log(pc.dim(`Run: ${runId}`));
+        // Lazy import to avoid Docker dependency when not using --local
+        const { LocalRunner } = await import("../../lib/local-runner.js");
+        const runner = new LocalRunner({
+            challengeData,
+            challengeConfig: config,
+            datapackPath: challenge.builtDatapackPath,
+            arenaImageOverride: flags["arena-image"],
+            apiUrl,
+            apiKey: flags["api-key"],
+            jobPayload,
+            jobId,
+            runId,
+        });
+        // Handle graceful shutdown
+        const cleanup = async () => {
+            this.log(pc.yellow("\n>> Shutting down..."));
+            await runner.cleanup();
+            process.exit(0);
+        };
+        process.on("SIGINT", cleanup);
+        process.on("SIGTERM", cleanup);
+        try {
+            this.log(pc.blue(`\n>> Running challenge locally: ${challengeSlug}\n`));
+            await runner.run((msg) => this.log(msg));
+            this.log(pc.green("\n=== Local run complete ==="));
+        }
+        catch (error) {
+            this.error(pc.red(`Local run failed: ${error instanceof Error ? error.message : String(error)}`));
+        }
+        finally {
+            process.removeListener("SIGINT", cleanup);
+            process.removeListener("SIGTERM", cleanup);
+            await runner.cleanup();
+        }
+    }
     async run() {
         const { args, flags, argv } = await this.parse(Run);
-        const apiUrl = flags.studio ? flags["studio-api-url"] : flags["api-url"];
-        const api = new ApiClient(apiUrl, flags["api-key"]);
         const challengeSlug = args.challengeSlug;
         // Get extra arguments (after the challenge slug) for inline agent specification
         const agentArgs = argv.filter((arg) => arg !== challengeSlug);
+        // Local mode: run via Docker
+        if (flags.local) {
+            return this.runLocally(challengeSlug, flags, agentArgs);
+        }
+        const apiUrl = flags.studio ? flags["studio-api-url"] : flags["api-url"];
+        const api = new ApiClient(apiUrl, flags["api-key"]);
         let participants;
         if (agentArgs.length > 0) {
             // Parse inline agent specification

package/dist/config/releases/arena-minecraft.d.ts

@@ -0,0 +1 @@
+export declare const MINECRAFT_ARENA_MANAGER_TAG = "8534933";

package/dist/config/releases/arena-minecraft.js

@@ -0,0 +1,2 @@
+// Managed by https://github.com/Kradle-ai/arena-minecraft/actions/workflows/release.yaml
+export const MINECRAFT_ARENA_MANAGER_TAG = "8534933";

package/dist/lib/api-client.d.ts

@@ -76,6 +76,7 @@ export declare class ApiClient {
         challenge: string;
         participants: unknown[];
         jobType: "background" | "foreground" | "foreground_with_recording";
+        env?: "cloud" | "studio";
     }): Promise<{
         runIds?: string[] | undefined;
         participants?: Record<string, {
@@ -84,7 +85,19 @@ export declare class ApiClient {
             inputOrder: number;
         }> | undefined;
         id?: string | undefined;
+        jobApiKey?: string | undefined;
     }>;
+    /**
+     * Create a job and return the full unvalidated response.
+     * Used for local runs where the full job object is passed directly to the arena container
+     * (same approach as Studio).
+     */
+    runChallengeRaw(runData: {
+        challenge: string;
+        participants: unknown[];
+        jobType: "background" | "foreground" | "foreground_with_recording";
+        env?: "cloud" | "studio";
+    }): Promise<Record<string, unknown>>;
     deleteChallenge(challengeId: string): Promise<void>;
     /**
      * Get the status of a run.

package/dist/lib/api-client.js

@@ -247,6 +247,18 @@ export class ApiClient {
             body: JSON.stringify(runData),
         }, JobResponseSchema);
     }
+    /**
+     * Create a job and return the full unvalidated response.
+     * Used for local runs where the full job object is passed directly to the arena container
+     * (same approach as Studio).
+     */
+    async runChallengeRaw(runData) {
+        const response = await this.request("jobs", {
+            method: "POST",
+            body: JSON.stringify(runData),
+        });
+        return response.json();
+    }
     async deleteChallenge(challengeId) {
         const url = `challenges/${challengeId}`;
         await this.delete(url);

package/dist/lib/local-runner.d.ts

@@ -0,0 +1,62 @@
+import type { ChallengeConfigSchemaType, ChallengeSchemaType } from "./schemas.js";
+export interface LocalRunnerConfig {
+    challengeData: ChallengeSchemaType;
+    challengeConfig: ChallengeConfigSchemaType;
+    datapackPath: string;
+    arenaImageOverride?: string;
+    apiUrl: string;
+    apiKey: string;
+    /** Full job response from backend — passed directly to the arena (same as Studio) */
+    jobPayload: Record<string, unknown>;
+    jobId: string;
+    runId: string;
+}
+type LogFn = (msg: string) => void;
+export declare class LocalRunner {
+    private config;
+    private mcContainerId;
+    private arenaContainerId;
+    private logProcess;
+    private tempDir;
+    private shutdownInProgress;
+    constructor(config: LocalRunnerConfig);
+    /**
+     * Main orchestration — starts MC server + arena, streams logs, waits for completion.
+     */
+    run(log: LogFn): Promise<void>;
+    /**
+     * Gracefully shut down all containers and clean up temp files.
+     */
+    cleanup(): Promise<void>;
+    private ensureDockerAvailable;
+    private resolveArenaImage;
+    private pullImageIfNeeded;
+    private downloadWorld;
+    private findLevelDat;
+    private startMinecraftServer;
+    private waitForServerReady;
+    private startArena;
+    /**
+     * Write a small datapack that auto-ops any player who joins.
+     * Uses a tick function with function-permission-level=4 to run /op on new players.
+     */
+    private writeAutoOpDatapack;
+    /**
+     * Generate an offline-mode UUID from a Minecraft username.
+     * Replicates the Java algorithm: UUID.nameUUIDFromBytes("OfflinePlayer:" + name)
+     */
+    private generateOfflineUUID;
+    private streamLogs;
+    private waitForCompletion;
+    private stopContainer;
+    /**
+     * Find and remove orphaned containers from previous local runs.
+     */
+    static cleanupOrphans(log?: LogFn): void;
+    /**
+     * Run a Docker command with PATH augmented for macOS Docker Desktop.
+     */
+    private docker;
+    private getDockerEnv;
+}
+export {};

package/dist/lib/local-runner.js

@@ -0,0 +1,432 @@
+import { execFileSync, execSync, spawn } from "node:child_process";
+import crypto from "node:crypto";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import pc from "picocolors";
+import * as tar from "tar";
+import { MINECRAFT_ARENA_MANAGER_TAG } from "../config/releases/arena-minecraft.js";
+const MC_SERVER_IMAGE = "marctv/minecraft-papermc-server:1.20.4";
+const DEFAULT_ARENA_IMAGE_TEMPLATE = "us-central1-docker.pkg.dev/kradle-prod-449119/prod-arenas/minecraft:{SHA}";
+const MC_PORT = 25565;
+const SERVER_READY_TIMEOUT_MS = 120_000;
+const SERVER_READY_POLL_MS = 3_000;
+const CONTAINER_NAME_PREFIX_MC = "kradle-mc-server";
+const CONTAINER_NAME_PREFIX_ARENA = "kradle-arena";
+export class LocalRunner {
+    config;
+    mcContainerId = null;
+    arenaContainerId = null;
+    logProcess = null;
+    tempDir = null;
+    shutdownInProgress = false;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Main orchestration — starts MC server + arena, streams logs, waits for completion.
+     */
+    async run(log) {
+        this.ensureDockerAvailable();
+        const arenaImage = this.resolveArenaImage();
+        log(`Arena image: ${arenaImage}`);
+        // Pull images
+        log("Pulling Docker images (this may take a while on first run)...");
+        this.pullImageIfNeeded(MC_SERVER_IMAGE, log);
+        this.pullImageIfNeeded(arenaImage, log);
+        // Clean up orphaned containers from previous runs
+        LocalRunner.cleanupOrphans(log);
+        // Prepare server directory (marctv image mounts entire /data)
+        this.tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "kradle-local-run-"));
+        const serverDir = path.join(this.tempDir, "server");
+        const worldDir = path.join(serverDir, "world");
+        await fs.mkdir(worldDir, { recursive: true });
+        // Download world
+        const worldSlug = this.config.challengeData.world;
+        if (worldSlug) {
+            log(`Downloading world: ${worldSlug}...`);
+            await this.downloadWorld(worldDir);
+        }
+        else {
+            log("No world specified, using empty world.");
+        }
+        // Start Minecraft server
+        log("Starting Minecraft server...");
+        this.mcContainerId = await this.startMinecraftServer(serverDir, worldDir);
+        log(`MC server container: ${this.mcContainerId.slice(0, 12)}`);
+        // Wait for server to be ready
+        log("Waiting for Minecraft server to be ready...");
+        await this.waitForServerReady(log);
+        log("");
+        log(pc.green("========================================"));
+        log(pc.green("  Minecraft server is ready!"));
+        log(pc.green(`  Connect to localhost:${MC_PORT} to join the live game`));
+        log(pc.green("  You will be automatically OP'd on join"));
+        log(pc.green("========================================"));
+        log("");
+        // Start arena-minecraft
+        log("Starting arena-minecraft...");
+        this.arenaContainerId = this.startArena(arenaImage);
+        log(`Arena container: ${this.arenaContainerId.slice(0, 12)}`);
+        // Stream arena logs
+        log("\n--- Arena logs ---\n");
+        this.logProcess = this.streamLogs(this.arenaContainerId, log);
+        // Wait for arena to finish
+        await this.waitForCompletion();
+        log("\n--- Arena finished ---\n");
+    }
+    /**
+     * Gracefully shut down all containers and clean up temp files.
+     */
+    async cleanup() {
+        if (this.shutdownInProgress)
+            return;
+        this.shutdownInProgress = true;
+        // Kill log streaming
+        if (this.logProcess) {
+            this.logProcess.kill();
+            this.logProcess = null;
+        }
+        // Graceful arena shutdown
+        if (this.arenaContainerId) {
+            try {
+                await fetch(`http://localhost:3002/shutdown`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ reason: "CLI shutdown" }),
+                    signal: AbortSignal.timeout(10_000),
+                });
+                await new Promise((r) => setTimeout(r, 3_000));
+            }
+            catch {
+                // Arena may already be stopped
+            }
+            this.stopContainer(this.arenaContainerId);
+            this.arenaContainerId = null;
+        }
+        // Stop MC server
+        if (this.mcContainerId) {
+            this.stopContainer(this.mcContainerId);
+            this.mcContainerId = null;
+        }
+        // Clean up temp directory
+        if (this.tempDir) {
+            await fs.rm(this.tempDir, { recursive: true, force: true });
+            this.tempDir = null;
+        }
+    }
+    // --- Private methods ---
+    ensureDockerAvailable() {
+        try {
+            this.docker("info", { stdio: "ignore" });
+        }
+        catch {
+            throw new Error("Docker is required for --local runs but is not available.\n" +
+                "Make sure Docker Desktop is running, or install it from https://docker.com");
+        }
+    }
+    resolveArenaImage() {
+        if (this.config.arenaImageOverride) {
+            return this.config.arenaImageOverride;
+        }
+        return DEFAULT_ARENA_IMAGE_TEMPLATE.replace("{SHA}", MINECRAFT_ARENA_MANAGER_TAG);
+    }
+    pullImageIfNeeded(image, log) {
+        try {
+            this.docker(`inspect --type=image ${image}`, { stdio: "ignore" });
+        }
+        catch {
+            log(`Pulling ${image}...`);
+            this.docker(`pull ${image}`, { stdio: "inherit" });
+        }
+    }
+    async downloadWorld(worldDir) {
+        const worldSlug = this.config.challengeData.world;
+        if (!worldSlug)
+            return;
+        const api = new (await import("./api-client.js")).ApiClient(this.config.apiUrl, this.config.apiKey);
+        const { downloadUrl } = await api.getWorldDownloadUrl(worldSlug);
+        const response = await fetch(downloadUrl);
+        if (!response.ok) {
+            throw new Error(`Failed to download world "${worldSlug}": ${response.status} ${response.statusText}`);
+        }
+        // Save and extract tarball
+        const tarballPath = path.join(worldDir, "world.tar.gz");
+        const buffer = await response.arrayBuffer();
+        await fs.writeFile(tarballPath, Buffer.from(buffer));
+        // Extract to temp, then find level.dat root
+        const extractDir = path.join(worldDir, "_extract");
+        await fs.mkdir(extractDir, { recursive: true });
+        await tar.extract({ file: tarballPath, cwd: extractDir });
+        // Find the directory containing level.dat (may be nested under an ID folder)
+        const levelDatDir = await this.findLevelDat(extractDir);
+        // Move world files to worldDir root
+        const entries = await fs.readdir(levelDatDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const src = path.join(levelDatDir, entry.name);
+            const dst = path.join(worldDir, entry.name);
+            await fs.rename(src, dst);
+        }
+        // Clean up extraction artifacts
+        await fs.rm(extractDir, { recursive: true, force: true });
+        await fs.rm(tarballPath, { force: true });
+    }
+    async findLevelDat(dir) {
+        if (existsSync(path.join(dir, "level.dat"))) {
+            return dir;
+        }
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const sub = path.join(dir, entry.name);
+                if (existsSync(path.join(sub, "level.dat"))) {
+                    return sub;
+                }
+            }
+        }
+        throw new Error(`Could not find level.dat in downloaded world`);
+    }
+    async startMinecraftServer(serverDir, worldDir) {
+        const containerName = `${CONTAINER_NAME_PREFIX_MC}-${crypto.randomUUID().slice(0, 8)}`;
+        const gameMode = this.config.challengeConfig.challengeConfig?.gameMode ?? "survival";
+        // Write server.properties (marctv image has no env vars for these)
+        const serverProperties = [
+            `server-port=${MC_PORT}`,
+            `max-players=10`,
+            `gamemode=${gameMode}`,
+            `difficulty=normal`,
+            `spawn-protection=0`,
+            `online-mode=false`,
+            `enable-command-block=false`,
+            `enable-rcon=true`,
+            `rcon.password=minecraft`,
+            `rcon.port=25575`,
+            `level-name=world`,
+            `function-permission-level=4`,
+        ].join("\n");
+        await fs.writeFile(path.join(serverDir, "server.properties"), serverProperties);
+        // Write ops.json with offline-mode UUIDs for watcher/viewer
+        const operators = [
+            { name: "watcher", uuid: this.generateOfflineUUID("watcher") },
+            { name: "KradleWebViewer", uuid: this.generateOfflineUUID("KradleWebViewer") },
+        ];
+        const opsJson = operators.map((op) => ({
+            uuid: op.uuid,
+            name: op.name,
+            level: 4,
+            bypassesPlayerLimit: false,
+        }));
+        await fs.writeFile(path.join(serverDir, "ops.json"), JSON.stringify(opsJson, null, 2));
+        // Copy datapack into world dir
+        const datapackDst = path.join(worldDir, "datapacks", "kradle");
+        if (existsSync(this.config.datapackPath)) {
+            execSync(`cp -r "${this.config.datapackPath}" "${datapackDst}"`);
+        }
+        // Add auto-op datapack — ops any player who joins (local dev convenience)
+        await this.writeAutoOpDatapack(path.join(worldDir, "datapacks", "kradle-local-ops"));
+        const args = [
+            "run",
+            "-d",
+            "--name",
+            containerName,
+            "-p",
+            `${MC_PORT}:${MC_PORT}`,
+            "-v",
+            `${serverDir}:/data`,
+            "-e",
+            "MEMORYSIZE=2G",
+            MC_SERVER_IMAGE,
+        ];
+        return this.docker(args.join(" ")).trim();
+    }
+    async waitForServerReady(log) {
+        const start = Date.now();
+        while (Date.now() - start < SERVER_READY_TIMEOUT_MS) {
+            try {
+                const logs = this.docker(`logs ${this.mcContainerId}`).toString();
+                if (logs.includes("Done (")) {
+                    return;
+                }
+            }
+            catch {
+                // Container may not be ready yet
+            }
+            const elapsed = Math.round((Date.now() - start) / 1000);
+            log(`  Waiting... (${elapsed}s)`);
+            await new Promise((r) => setTimeout(r, SERVER_READY_POLL_MS));
+        }
+        throw new Error(`Minecraft server did not become ready within ${SERVER_READY_TIMEOUT_MS / 1000}s`);
+    }
+    startArena(arenaImage) {
+        const containerName = `${CONTAINER_NAME_PREFIX_ARENA}-${crypto.randomUUID().slice(0, 8)}`;
+        // Pass the full backend job response directly to the arena — same as Studio.
+        const jobPayload = JSON.stringify(this.config.jobPayload);
+        // Arena prepends /v0 to all API paths, so strip it from our URL to avoid /v0/v0
+        const arenaApiUrl = this.config.apiUrl.replace(/\/v0\/?$/, "");
+        // Derive agent URL from API URL (dev-api → dev-agents, api → agents, etc.)
+        const agentBaseUrl = arenaApiUrl.replace("api.kradle.ai", "agents.kradle.ai");
+        const args = [
+            "run",
+            "-d",
+            "--name",
+            containerName,
+            `--net=container:${this.mcContainerId}`,
+            "-e",
+            "PORT=3002",
+            "-e",
+            `KRADLE_API_URL=${arenaApiUrl}`,
+            "-e",
+            `PROMPT_AGENT_BASE_URL=${agentBaseUrl}`,
+            "-e",
+            "MAX_IDLE_TIME=-1",
+            arenaImage,
+            `--job=${jobPayload}`,
+        ];
+        // Use execFileSync to bypass shell — the JSON payload contains quotes,
+        // parentheses, and other characters that break shell parsing.
+        const result = execFileSync("docker", args, {
+            encoding: "utf-8",
+            env: this.getDockerEnv(),
+        });
+        return (result ?? "").trim();
+    }
+    /**
+     * Write a small datapack that auto-ops any player who joins.
+     * Uses a tick function with function-permission-level=4 to run /op on new players.
+     */
+    async writeAutoOpDatapack(datapackDir) {
+        const functionsDir = path.join(datapackDir, "data", "kradle_local", "functions");
+        const tagsDir = path.join(datapackDir, "data", "minecraft", "tags", "functions");
+        await fs.mkdir(functionsDir, { recursive: true });
+        await fs.mkdir(tagsDir, { recursive: true });
+        await fs.writeFile(path.join(datapackDir, "pack.mcmeta"), JSON.stringify({ pack: { pack_format: 26, description: "Auto-OP for local dev" } }));
+        // Tick function: op any player not yet tagged, then tag them so it only runs once
+        await fs.writeFile(path.join(functionsDir, "auto_op.mcfunction"), "execute as @a[tag=!kradle_opped] run op @s[type=player]\nexecute as @a[tag=!kradle_opped] run tag @s add kradle_opped\n");
+        // Register as a tick function
+        await fs.writeFile(path.join(tagsDir, "tick.json"), JSON.stringify({ values: ["kradle_local:auto_op"] }));
+    }
+    /**
+     * Generate an offline-mode UUID from a Minecraft username.
+     * Replicates the Java algorithm: UUID.nameUUIDFromBytes("OfflinePlayer:" + name)
+     */
+    generateOfflineUUID(username) {
+        const md5 = crypto.createHash("md5").update(`OfflinePlayer:${username}`).digest();
+        const bytes = [...md5];
+        bytes[6] = (bytes[6] & 0x0f) | 0x30; // version 3
+        bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant 2
+        const hex = bytes.map((b) => b.toString(16).padStart(2, "0"));
+        return [
+            hex.slice(0, 4).join(""),
+            hex.slice(4, 6).join(""),
+            hex.slice(6, 8).join(""),
+            hex.slice(8, 10).join(""),
+            hex.slice(10, 16).join(""),
+        ].join("-");
+    }
+    streamLogs(containerId, log) {
+        const proc = spawn("docker", ["logs", "-f", containerId], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: this.getDockerEnv(),
+        });
+        proc.stdout?.on("data", (data) => {
+            for (const line of data.toString().split("\n")) {
+                if (line.trim())
+                    log(line);
+            }
+        });
+        proc.stderr?.on("data", (data) => {
+            for (const line of data.toString().split("\n")) {
+                if (line.trim())
+                    log(line);
+            }
+        });
+        return proc;
+    }
+    async waitForCompletion() {
+        // Wait for the arena container to exit
+        return new Promise((resolve) => {
+            const check = () => {
+                try {
+                    const result = this.docker(`inspect --format={{.State.Running}} ${this.arenaContainerId}`).trim();
+                    if (result === "false") {
+                        resolve();
+                        return;
+                    }
+                }
+                catch {
+                    // Container removed or not found — treat as finished
+                    resolve();
+                    return;
+                }
+                setTimeout(check, 3_000);
+            };
+            // Start checking after a brief delay
+            setTimeout(check, 5_000);
+        });
+    }
+    stopContainer(containerId) {
+        try {
+            this.docker(`stop ${containerId}`, { timeout: 30_000 });
+        }
+        catch {
+            // May already be stopped
+        }
+        try {
+            this.docker(`rm -f ${containerId}`);
+        }
+        catch {
+            // May already be removed
+        }
+    }
+    /**
+     * Find and remove orphaned containers from previous local runs.
+     */
+    static cleanupOrphans(log) {
+        const env = { ...process.env, PATH: `${process.env.PATH}:/opt/homebrew/bin:/usr/local/bin` };
+        for (const prefix of [CONTAINER_NAME_PREFIX_MC, CONTAINER_NAME_PREFIX_ARENA]) {
+            try {
+                const output = execSync(`docker ps -a --filter "name=${prefix}" --format "{{.ID}}"`, {
+                    encoding: "utf-8",
+                    env,
+                }).trim();
+                if (output) {
+                    for (const id of output.split("\n")) {
+                        if (id.trim()) {
+                            log?.(`Cleaning up orphaned container: ${id.trim().slice(0, 12)}`);
+                            try {
+                                execSync(`docker rm -f ${id.trim()}`, { env, stdio: "ignore" });
+                            }
+                            catch {
+                                // Ignore
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                // Docker not available or no containers found
+            }
+        }
+    }
+    /**
+     * Run a Docker command with PATH augmented for macOS Docker Desktop.
+     */
+    docker(args, options) {
+        const env = this.getDockerEnv();
+        const stdio = options?.stdio ?? "pipe";
+        const result = execSync(`docker ${args}`, {
+            encoding: "utf-8",
+            env,
+            stdio,
+            timeout: options?.timeout,
+        });
+        return result ?? "";
+    }
+    getDockerEnv() {
+        return {
+            ...process.env,
+            PATH: `${process.env.PATH}:/opt/homebrew/bin:/usr/local/bin`,
+        };
+    }
+}

package/dist/lib/schemas.d.ts

@@ -192,6 +192,7 @@ export declare const JobResponseSchema: z.ZodObject<{
         inputOrder: z.ZodNumber;
     }, z.core.$strip>>>;
     id: z.ZodOptional<z.ZodString>;
+    jobApiKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const RunStatusSchema: z.ZodObject<{
     id: z.ZodString;

package/dist/lib/schemas.js

@@ -73,6 +73,7 @@ export const JobResponseSchema = z.object({
     runIds: z.array(z.string()).optional(),
     participants: z.record(z.string(), RunParticipantSchema).optional(),
     id: z.string().optional(),
+    jobApiKey: z.string().optional(),
 });
 export const RunStatusSchema = z.object({
     id: z.string(),

package/oclif.manifest.json

@@ -87,50 +87,6 @@
         "update.js"
       ]
     },
-    "agent:list": {
-      "aliases": [],
-      "args": {},
-      "description": "List all agents",
-      "examples": [
-        "<%= config.bin %> <%= command.id %>"
-      ],
-      "flags": {
-        "api-key": {
-          "description": "Kradle API key",
-          "env": "KRADLE_API_KEY",
-          "name": "api-key",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "api-url": {
-          "description": "Kradle Web API URL",
-          "env": "KRADLE_API_URL",
-          "name": "api-url",
-          "required": true,
-          "default": "https://api.kradle.ai/v0",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "agent:list",
-      "pluginAlias": "kradle",
-      "pluginName": "kradle",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "agent",
-        "list.js"
-      ]
-    },
     "ai-docs:challenges-sdk": {
       "aliases": [],
       "args": {
@@ -579,7 +535,10 @@
         "<%= config.bin %> <%= command.id %> my-challenge --no-open",
         "<%= config.bin %> <%= command.id %> my-challenge --no-wait",
         "<%= config.bin %> <%= command.id %> my-challenge team-kradle:gemini-3-flash,team-kradle:grok-4-1-fast",
-        "<%= config.bin %> <%= command.id %> capture-the-flag red=team-kradle:gemini-3-flash blue=team-kradle:grok-4-1-fast"
+        "<%= config.bin %> <%= command.id %> capture-the-flag red=team-kradle:gemini-3-flash blue=team-kradle:grok-4-1-fast",
+        "<%= config.bin %> <%= command.id %> my-challenge --local",
+        "<%= config.bin %> <%= command.id %> my-challenge --local team-kradle:gemini-3-flash,team-kradle:grok-4-1-fast",
+        "<%= config.bin %> <%= command.id %> my-challenge --local --arena-image us-central1-docker.pkg.dev/mckradle-3c267/dev-arenas/minecraft:abc1234"
       ],
       "flags": {
         "studio": {
@@ -596,6 +555,21 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "local": {
+          "char": "l",
+          "description": "Run the challenge locally using Docker (spins up MC server + arena-minecraft)",
+          "name": "local",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "arena-image": {
+          "description": "Override arena-minecraft Docker image URL (for testing dev/staging builds)",
+          "env": "KRADLE_ARENA_IMAGE",
+          "name": "arena-image",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "no-open": {
           "description": "Don't open the run URL in the browser",
           "name": "no-open",
@@ -668,6 +642,15 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "challenges-path": {
+          "description": "Absolute path to the challenges directory",
+          "env": "KRADLE_CHALLENGES_PATH",
+          "name": "challenges-path",
+          "default": "~/Documents/kradle-studio/challenges",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -1407,6 +1390,50 @@
         "push.js"
       ]
     },
+    "agent:list": {
+      "aliases": [],
+      "args": {},
+      "description": "List all agents",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {
+        "api-key": {
+          "description": "Kradle API key",
+          "env": "KRADLE_API_KEY",
+          "name": "api-key",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-url": {
+          "description": "Kradle Web API URL",
+          "env": "KRADLE_API_URL",
+          "name": "api-url",
+          "required": true,
+          "default": "https://api.kradle.ai/v0",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "agent:list",
+      "pluginAlias": "kradle",
+      "pluginName": "kradle",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "agent",
+        "list.js"
+      ]
+    },
     "challenge:runs:get": {
       "aliases": [],
       "args": {
@@ -1528,5 +1555,5 @@
       ]
     }
   },
-  "version": "0.6.7"
+  "version": "0.6.8"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kradle",
-	"version": "0.6.7",
+	"version": "0.6.8",
 	"description": "Kradle's CLI. Manage challenges, experiments, agents and more!",
 	"keywords": [
 		"cli"

package/static/ai_docs/LLM_CLI_REFERENCE.md

@@ -417,11 +417,13 @@ When no agents are specified, the command enters interactive mode:
 | Flag | Short | Description |
 |------|-------|-------------|
 | `--studio` | `-s` | Run in local studio environment instead of production |
+| `--local` | `-l` | Run locally using Docker (spins up MC server + arena-minecraft containers) |
+| `--arena-image` | | Override arena-minecraft Docker image URL (env: `KRADLE_ARENA_IMAGE`) |
 | `--no-open` | | Don't open the run URL in the browser |
 | `--no-wait` | | Don't wait for completion (fire and forget) |
 | `--no-summary` | | Don't wait for the AI-generated summary |
 
-**Behavior:**
+**Behavior (remote, default):**
 1. Parses inline agents or enters interactive mode for agent selection
 2. Creates a run with the challenge and specified participants
 3. Opens the run URL in the browser (unless `--no-open`)
@@ -430,6 +432,31 @@ When no agents are specified, the command enters interactive mode:
 
 **Terminal states:** The polling stops when the run reaches: `finished`, `game_over`, `error`, `completed`, `cancelled`, `timeout`, or `failed`.
 
+**Behavior (local, with `--local`):**
+1. Parses inline agents or enters interactive mode for agent selection
+2. Fetches challenge config from the API
+3. Builds the challenge datapack locally (with validation)
+4. Creates a real backend job (`env: "studio"`) — returns full job object with agent configs, participant IDs, etc.
+5. Downloads the challenge world from the cloud
+6. Starts a Minecraft server Docker container (`marctv/minecraft-papermc-server:1.20.4`)
+7. Starts an arena-minecraft Docker container (shares MC server network), passing the full backend job response
+8. All players who join the MC server are automatically OP'd (via an auto-op datapack)
+9. Streams arena logs to stdout until the run completes
+10. Ctrl+C triggers graceful shutdown (arena `/shutdown` endpoint, then container stop/remove)
+
+**Local mode requirements:**
+- Docker Desktop must be running (Docker is only checked when `--local` is used)
+- The challenge must exist locally (with `challenge.ts` and `config.ts`)
+- First run pulls images which may take several minutes
+- The agent URL is derived from the API URL (e.g., `dev-api.kradle.ai` → `dev-agents.kradle.ai`)
+
+**Local mode incompatibilities:** `--local` cannot be combined with `--studio`, `--no-open`, `--no-wait`, `--screenshots`, or `--record`.
+
+**Arena image override:** The `--arena-image` flag (or `KRADLE_ARENA_IMAGE` env var) allows testing dev or staging arena builds:
+- Dev: `us-central1-docker.pkg.dev/mckradle-3c267/dev-arenas/minecraft:<sha>`
+- Staging: `us-central1-docker.pkg.dev/kradle-staging/staging-arenas/minecraft:<sha>`
+- Prod (default): `us-central1-docker.pkg.dev/kradle-prod-449119/prod-arenas/minecraft:<sha>`
+
 **Examples:**
 ```bash
 # Interactive mode - prompts for agent selection
@@ -454,6 +481,13 @@ kradle challenge run my-challenge team-kradle:gemini-3-flash --no-open
 
 # Fire and forget (don't wait for completion)
 kradle challenge run my-challenge team-kradle:gemini-3-flash --no-wait
+
+# Run locally with Docker
+kradle challenge run my-challenge --local team-kradle:gemini-3-flash,team-kradle:grok-4-1-fast
+
+# Run locally with a dev arena image
+kradle challenge run my-challenge --local \
+  --arena-image us-central1-docker.pkg.dev/mckradle-3c267/dev-arenas/minecraft:abc1234
 ```
 
 ---
@@ -1288,6 +1322,7 @@ kradle challenge build --all --public
 | `kradle challenge pull [name]` | Pull challenge from cloud |
 | `kradle challenge watch <name>` | Watch and auto-rebuild |
 | `kradle challenge run <name>` | Run challenge and wait for completion |
+| `kradle challenge run <name> --local` | Run challenge locally using Docker |
 | `kradle challenge runs list` | List recent runs |
 | `kradle challenge runs get <run-id>` | Get details and logs for a run |
 | `kradle experiment create <name>` | Create new experiment |