kradle 0.6.6 → 0.6.8

package/README.md

@@ -81,23 +81,24 @@ This creates a `challenges/<challenge-name>/` folder with:
 
 ### Build Challenge
 
-Build, validate, and upload challenge datapack:
+Build and validate challenge datapacks locally, with optional upload:
 
 ```bash
 kradle challenge build <challenge-name>
+kradle challenge build <challenge-name> --no-upload    # Build locally only (no cloud upload)
 kradle challenge build <challenge-name> --no-validate  # Skip validation
 kradle challenge build <challenge-name> --public       # Upload as public
 kradle challenge build --all                           # Build all local challenges
 ```
 
 This command:
-1. Creates the challenge in the cloud (if it doesn't already exist)
-2. Builds the datapack by executing `challenge.ts`
-3. Validates the datapack using Spyglass (blocks upload if errors found)
-4. Uploads `config.ts` to cloud
-5. Uploads the datapack to GCS
+1. Builds the datapack by executing `challenge.ts`
+2. Validates the datapack using Spyglass (unless `--no-validate`)
+3. If upload is enabled (default), creates the challenge in the cloud if needed
+4. If upload is enabled (default), uploads `config.ts` and datapack
 
-Validation checks `.mcfunction` files for syntax errors, invalid commands, and other issues. Use `--no-validate` to skip this step.
+Use `--no-upload` to build locally only. Use `--no-validate` to skip validation.
+`--public` is only valid when upload is enabled (default).
 
 ### Delete Challenge
 
@@ -176,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:
@@ -478,7 +512,7 @@ Each challenge is a folder in `challenges/<slug>/` containing:
 1. `kradle challenge create <slug>` creates the folder with `challenge.ts`
 2. The create command automatically builds, uploads, and downloads the config from the cloud API
 3. The downloaded JSON is converted into a typed TypeScript `config.ts` file
-4. `kradle challenge build <slug>` automatically uploads `config.ts` (if it exists) before building the datapack
+4. `kradle challenge build <slug>` builds datapacks locally and uploads `config.ts` + datapack by default (use `--no-upload` for local-only build)
 5. You can modify `config.ts` locally and run `build` to sync changes to the cloud
 
 ## Architecture
@@ -507,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/build.d.ts

@@ -6,13 +6,15 @@ export default class Build extends Command {
         challengeSlug: import("@oclif/core/interfaces").Arg<string | undefined>;
     };
     static flags: {
-        "api-key": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
-        "api-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>;
         all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         public: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         "no-validate": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "no-upload": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "api-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "api-key": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static strict: boolean;
     run(): Promise<void>;
+    private requireApiKey;
 }

package/dist/commands/challenge/build.js

@@ -5,7 +5,7 @@ import { extractShortSlug, getChallengeSlugArgument } from "../../lib/arguments.
 import { Challenge } from "../../lib/challenge.js";
 import { getConfigFlags } from "../../lib/flags.js";
 export default class Build extends Command {
-    static description = "Build and upload challenge datapack and config";
+    static description = "Build challenge datapack locally, with optional upload";
     static examples = [
         "<%= config.bin %> <%= command.id %> my-challenge",
         "<%= config.bin %> <%= command.id %> my-challenge my-other-challenge",
@@ -13,7 +13,7 @@ export default class Build extends Command {
     ];
     static args = {
         challengeSlug: getChallengeSlugArgument({
-            description: "Challenge slug to build and upload. Can be used multiple times to build and upload multiple challenges at once. Incompatible with --all flag.",
+            description: "Challenge slug to build. Can be used multiple times to build multiple challenges at once. Incompatible with --all flag.",
             required: false,
         }),
     };
@@ -21,10 +21,23 @@ export default class Build extends Command {
         all: Flags.boolean({ char: "a", description: "Build all challenges in the challenges directory", default: false }),
         public: Flags.boolean({ char: "p", description: "Upload challenges as public.", default: false }),
         "no-validate": Flags.boolean({
-            description: "Skip datapack validation before upload",
+            description: "Skip datapack validation",
             default: false,
         }),
-        ...getConfigFlags("api-key", "api-url", "challenges-path"),
+        "no-upload": Flags.boolean({
+            description: "Build datapack locally only (skip cloud config/datapack upload)",
+            default: false,
+        }),
+        "api-url": Flags.string({
+            description: "Kradle Web API URL",
+            env: "KRADLE_API_URL",
+            default: "https://api.kradle.ai/v0",
+        }),
+        "api-key": Flags.string({
+            description: "Kradle API key",
+            env: "KRADLE_API_KEY",
+        }),
+        ...getConfigFlags("challenges-path"),
     };
     static strict = false;
     async run() {
@@ -32,6 +45,9 @@ export default class Build extends Command {
         if (flags.all && argv.length > 0) {
             this.error(pc.red("Cannot use --all flag with challenge slugs"));
         }
+        if (flags["no-upload"] && flags.public) {
+            this.error(pc.red("Cannot use --public with --no-upload"));
+        }
         if (!flags.all && argv.length === 0) {
             // Show help if no challenge slugs are provided - https://github.com/oclif/oclif/issues/183#issuecomment-1933104981
             await new (await loadHelpClass(this.config))(this.config).showHelp([Build.id]);
@@ -41,7 +57,8 @@ export default class Build extends Command {
             this.log(pc.blue("Building all challenges"));
         }
         const challengeSlugs = flags.all ? await Challenge.getLocalChallenges() : argv;
-        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        const shouldUpload = !flags["no-upload"];
+        const api = shouldUpload ? new ApiClient(flags["api-url"], this.requireApiKey(flags["api-key"])) : null;
         for (const challengeSlug of challengeSlugs) {
             // Validate that the challenge exists locally
             const validation = await Challenge.validateForLocalOperation(challengeSlug, flags["challenges-path"]);
@@ -51,10 +68,17 @@ export default class Build extends Command {
             const challenge = new Challenge(extractShortSlug(challengeSlug), flags["challenges-path"]);
             this.log(pc.blue(`==== Building challenge: ${challenge.shortSlug} ====`));
             try {
-                await challenge.buildAndUpload(api, {
-                    asPublic: flags.public,
-                    validate: !flags["no-validate"],
-                });
+                if (shouldUpload && api) {
+                    await challenge.buildAndUpload(api, {
+                        asPublic: flags.public,
+                        validate: !flags["no-validate"],
+                    });
+                }
+                else {
+                    await challenge.buildLocal({
+                        validate: !flags["no-validate"],
+                    });
+                }
             }
             catch (error) {
                 this.error(pc.red(`Build failed: ${error instanceof Error ? error.message : String(error)}`));
@@ -62,4 +86,11 @@ export default class Build extends Command {
             this.log();
         }
     }
+    requireApiKey(apiKey) {
+        if (apiKey) {
+            return apiKey;
+        }
+        this.error(pc.red("Missing required flag --api-key (or KRADLE_API_KEY) unless using --no-upload"));
+        throw new Error("Unreachable");
+    }
 }

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/challenge.d.ts

@@ -51,6 +51,18 @@ export declare class Challenge {
      */
     build(silent?: boolean, config?: ChallengeConfigSchemaType): Promise<void>;
     loadConfig(): Promise<ChallengeConfigSchemaType>;
+    /**
+     * Build the challenge datapack locally.
+     * @param options - Build options
+     * @param options.validate - Whether to validate the datapack after build (default: true).
+     * @returns The loaded config and datapack hash.
+     */
+    buildLocal(options?: {
+        validate?: boolean;
+    }): Promise<{
+        config: ChallengeConfigSchemaType;
+        datapackHash: string;
+    }>;
     /**
      * Build the challenge datapack and upload it to the cloud.
      * @param api - The API client to use.

package/dist/lib/challenge.js

@@ -162,17 +162,15 @@ export class Challenge {
         }
     }
     /**
-     * Build the challenge datapack and upload it to the cloud.
-     * @param api - The API client to use.
+     * Build the challenge datapack locally.
      * @param options - Build options
-     * @param options.asPublic - Whether the challenge should be uploaded as public.
-     * @param options.validate - Whether to validate the datapack before upload (default: true).
-     * @returns The config and datapack hash.
+     * @param options.validate - Whether to validate the datapack after build (default: true).
+     * @returns The loaded config and datapack hash.
      */
-    async buildAndUpload(api, options = { asPublic: false, validate: true }) {
-        const { asPublic, validate = true } = options;
+    async buildLocal(options = { validate: true }) {
+        const { validate = true } = options;
         // Start validation service initialization in parallel with build (if validation enabled)
-        // This overlaps the ~1.5s init time with the build process
+        // This overlaps the init time with the build process.
         let validationService = null;
         if (validate) {
             validationService = ValidationService.create(this.builtDatapackPath);
@@ -182,19 +180,12 @@ export class Challenge {
             await validationService?.close();
             throw new Error(`Challenge "${this.shortSlug}" does not exist locally. Make sure both the challenge.ts file and the config.ts file exist.`);
         }
-        // Ensure challenge exists in the cloud
-        if (!(await api.challengeExists(this.shortSlug))) {
-            console.log(pc.yellow(`Challenge not found in cloud: ${this.shortSlug}`));
-            console.log(pc.yellow(`Creating challenge: ${this.shortSlug}`));
-            await api.createChallenge(this.shortSlug);
-            console.log(pc.green(`✓ Challenge created in cloud`));
-        }
         const config = await this.loadConfig();
         // Build datapack (validation service initializes in parallel)
         console.log(pc.blue(`>> Building datapack: ${this.shortSlug}`));
         await this.build(false, config);
         console.log(pc.green(`✓  Datapack built\n`));
-        // Validate datapack before uploading (if enabled)
+        // Validate datapack after building (if enabled)
         if (validate && validationService) {
             console.log(pc.blue(`>> Validating datapack: ${this.shortSlug}`));
             try {
@@ -202,13 +193,34 @@ export class Challenge {
                 console.log(formatValidationResult(validationResult));
                 console.log();
                 if (validationResult.hasErrors) {
-                    throw new Error(`Validation failed with ${validationResult.errors.length} error(s). Upload aborted.`);
+                    throw new Error(`Validation failed with ${validationResult.errors.length} error(s). Build aborted.`);
                 }
             }
             finally {
                 await validationService.close();
             }
         }
+        const datapackHash = await this.getDatapackHash();
+        return { config, datapackHash };
+    }
+    /**
+     * Build the challenge datapack and upload it to the cloud.
+     * @param api - The API client to use.
+     * @param options - Build options
+     * @param options.asPublic - Whether the challenge should be uploaded as public.
+     * @param options.validate - Whether to validate the datapack before upload (default: true).
+     * @returns The config and datapack hash.
+     */
+    async buildAndUpload(api, options = { asPublic: false, validate: true }) {
+        const { asPublic, validate = true } = options;
+        const { config, datapackHash } = await this.buildLocal({ validate });
+        // Ensure challenge exists in the cloud
+        if (!(await api.challengeExists(this.shortSlug))) {
+            console.log(pc.yellow(`Challenge not found in cloud: ${this.shortSlug}`));
+            console.log(pc.yellow(`Creating challenge: ${this.shortSlug}`));
+            await api.createChallenge(this.shortSlug);
+            console.log(pc.green(`✓ Challenge created in cloud`));
+        }
         // Ensure challenge's visibility is set to private - else, temporarily set it to private
         const cloudChallengeVisibility = (await api.getChallenge(this.shortSlug, ["visibility"])).visibility;
         if (cloudChallengeVisibility === "public") {
@@ -230,7 +242,6 @@ export class Challenge {
             await api.updateChallengeVisibility(this.shortSlug, "public");
             console.log(pc.green(`✓  Challenge visibility set to public\n`));
         }
-        const datapackHash = await this.getDatapackHash();
         return { config, datapackHash };
     }
     /**

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 {};