Run Codex 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;
• an OpenAI API key with access to Codex. If not, create an OpenAI API key.

​

Install the Blaxel CLI and SDK

1. Download and install the Blaxel CLI and log in to your Blaxel account:
   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

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

​

Create sandboxes

1. In the host environment, define the following variables:
   export BLAXEL_API_KEY=YOUR-BLAXEL-API-KEY-HERE
   export OPENAI_API_KEY=YOUR-OPENAI-API-KEY-HERE
   
2. Create a script named main.py (Python) or index.ts (TypeScript) in the same directory.
   TypeScript

   Python

   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");
     }
     const openaiApiKey = process.env.OPENAI_API_KEY;
     if (!openaiApiKey) {
       throw new Error("OPENAI_API_KEY environment variable is not set");
     }
   
     // Create application sandbox
     const appSandbox = await SandboxInstance.createIfNotExists({
       name: "nextjs-sandbox",
       image: "blaxel/nextjs:latest",
       memory: 4096,
       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 Codex sandbox
     const codexSandbox = await SandboxInstance.createIfNotExists({
       name: "codex-sandbox",
       image: "blaxel/codex:latest",
       memory: 4096,
       region: "us-pdx-1",
       envs: [
         { name: "OPENAI_API_KEY", value: openaiApiKey },
         { name: "BLAXEL_API_KEY", value: blaxelApiKey }
       ]
     });
     console.log("Codex sandbox created");
   }
   
   main();
   
   
   This script creates two Blaxel sandboxes:
   • codex-sandbox using Blaxel’s pre-built Codex image, which includes the Codex CLI
   • nextjs-sandbox using Blaxel’s Next.js base image
   In the Codex sandbox, it:
   • adds the Blaxel and OpenAI API keys to codex-sandbox as environment variables.
   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

   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.

​

Configure and test Codex

1. Connect to the Codex sandbox terminal:
   bl connect sandbox codex-sandbox
   
2. Configure Codex to connect to the application sandbox’s MCP server URL (obtained from the sandbox creation script in the previous section) with your Blaxel API key (set in the sandbox environment):
   codex mcp add sandbox --url YOUR-SANDBOX-MCP-URL-HERE  --bearer-token-env-var  BLAXEL_API_KEY
   
3. Start Codex and confirm that it is connected to the sandbox MCP server with the /mcp command. This command should return the list of tools available in the sandbox.

​

Test Codex

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