Run Claude Code in a sandbox

​

Prerequisites

• a Python or TypeScript development environment;
• a Blaxel account and API key. If not, sign up for a Blaxel account and create a Blaxel API key;
• a Claude account with an active subscription or an Anthropic Console account with usage-based billing, required by Claude Code. If not, sign up for an Anthropic account and obtain a subscription or API credits as required;

​

Install the Blaxel CLI and SDK

1. Download and install the Blaxel CLI and log in to your Blaxel account:
   Copy

   Ask AI

   bl login
   
2. In a new directory, install the Blaxel SDK (Python and TypeScript are both supported):
   TypeScript (npm)

   TypeScript (pnpm)

   TypeScript (yarn)

   TypeScript (bun)

   Python

   Copy

   Ask AI

   npm init # if new project
   npm install @blaxel/core
   

​

Create sandboxes

1. In the host environment, define the following variable:
   Copy

   Ask AI

   export BLAXEL_API_KEY=YOUR-BLAXEL-API-KEY-HERE
   
2. Create a script named main.py (Python) or index.ts (TypeScript) in the same directory.
   TypeScript

   Python

   Copy

   Ask AI

   import { SandboxInstance } from "@blaxel/core";
   
   async function main() {
     // Check for required variables
     const blaxelApiKey = process.env.BLAXEL_API_KEY;
     if (!blaxelApiKey) {
       throw new Error("BLAXEL_API_KEY environment variable is not set");
     }
   
     // Create application sandbox
     const appSandbox = await SandboxInstance.createIfNotExists({
       name: "nextjs-sandbox",
       image: "blaxel/nextjs:latest",
       memory: 4096,
       ports: [{ target: 3000, protocol: "HTTP" }],
       region: "us-pdx-1",
     });
     console.log("Application sandbox created");
   
     // Start dev server in application sandbox
     await appSandbox.process.exec({
       workingDir: "/blaxel/app",
       command: "npm run dev -- --hostname 0.0.0.0 --port 3000"
     });
     console.log("Application server started");
   
     // Create preview URL
     const appPreview = await appSandbox.previews.createIfNotExists({
       metadata: { name: "app-preview" },
       spec: {
         port: 3000,
         public: false,
       }
     });
     console.log("Preview URL created");
   
     // Create preview token
     // Valid for 24 hours
     const expiresAt = new Date(Date.now() + 1440 * 60 * 1000);
     const token = await appPreview.tokens.create(expiresAt);
   
     // Get preview URL
     console.log(`Preview URL: ${appPreview.spec.url}?bl_preview_token=${token.value}`);
     console.log(`MCP URL: ${appSandbox.metadata.url}/mcp`);
   
     // Create Claude Code sandbox
     const claudeSandbox = await SandboxInstance.createIfNotExists({
       name: "claude-sandbox",
       image: "blaxel/node:latest",
       memory: 4096,
       region: "us-pdx-1",
       envs: [
         { name: "BLAXEL_API_KEY", value: blaxelApiKey }
       ]
     });
     console.log("Claude Code sandbox created");
   }
   
   main();
   
   
   This script creates two Blaxel sandboxes:
   • claude-sandbox using Blaxel’s Node.js base image
   • nextjs-sandbox using Blaxel’s Next.js base image
   In the Claude Code sandbox, it:
   • adds the Blaxel API key to claude-sandbox as an environment variable named BLAXEL_API_KEY.
   In the application sandbox, it:
   • starts the Next.js dev server in nextjs-sandbox on port 3000;
   • creates a preview URL for the Next.js service running in nextjs-sandbox on port 3000;
   • creates an access token for the preview URL, valid for 24 hours;
   • returns the preview URL.
3. Run the script to create the sandboxes and preview URL:
   Python

   TypeScript

   Copy

   Ask AI

   python main.py
   
   Once complete, the script displays the generated preview URL for the Next.js application (for example, https://b186....preview.bl.run?bl_preview_token=cbba622560db78e...) and the MCP server URL (for example, https://sbx-nextjs-sandbox....bl.run/mcp) for the Next.js sandbox. Note these values, as you will require them in subsequent steps.

​

Install and configure Claude Code

1. Connect to the Claude Code sandbox terminal:
   Copy

   Ask AI

   bl connect sandbox claude-sandbox
   
2. Execute the following commands to install Claude Code in the sandbox and include it in the system PATH:
   Copy

   Ask AI

   apk add curl bash
   curl -fsSL https://claude.ai/install.sh | bash
   echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc && source ~/.bashrc
   
   For detailed installation instructions, refer to the Claude Code documentation.
3. Add the application sandbox’s MCP server URL (obtained from the sandbox creation script in the previous section) to Claude Code:
   Copy

   Ask AI

   claude mcp add --transport http sandbox YOUR-SANDBOX-MCP-URL-HERE  --header "Authorization: Bearer $BLAXEL_API_KEY"
   
4. Confirm that Claude Code is able to connect to the application sandbox’s MCP server. Run the following command and confirm that you see output like sandbox: .... connected:
   Copy

   Ask AI

   claude mcp list
   

​

Test Claude Code

claude

You have access to a sandbox environment over MCP. The sandbox includes tools to read and write files and directories and run commands. The sandbox includes a skeleton Next.js application at /blaxel/app. Update the application codebase and complete the coding task below.

You must make all your changes only in the sandbox.
Do not make any changes in the local environment.

Your task is: create a website for a new board game of your own invention, including an interactive demo

​

Resources