Use OpenAI Agents SDK with sandboxes

The OpenAI Agents SDK is an open source, production-grade library for building agentic applications leveraging the Codex harness. One of the most interesting features of this SDK is the ability to create agents that are backed by remote execution environments (sandboxes) in the cloud. This ability allows the harness to get access to its own computer to execute commands, work with files and directories, write code, and perform computations. This tutorial explores how you can use the OpenAI Agents SDK with Blaxel to create powerful sandbox-backed agents.

Prerequisites

An OpenAI API key. If not, sign up for an OpenAI account and obtain an API key.
A Blaxel account. If not, sign up for a Blaxel account.
A Blaxel workspace and API key. Learn about Blaxel workspaces and how to obtain a Blaxel API key.

The OpenAI Agents SDK is provider-agnostic and can be used with both OpenAI and non-OpenAI models. This tutorial uses OpenAI models, but you can also read about integrating other models with the Python SDK.

1. Install the Blaxel CLI and log in to Blaxel

Install the Blaxel CLI and log in to Blaxel using this command:

bl login

2. Install required dependencies

Create a directory for the project:

mkdir sandbox-agent && cd sandbox-agent

In your project directory, install the OpenAI Agent SDK with Blaxel support for the agent loop:

npm init # if new project
npm install @openai/agents-extensions @blaxel/core

pnpm init # if new project
pnpm install @openai/agents-extensions @blaxel/core

yarn init # if new project
yarn add @openai/agents-extensions @blaxel/core

bun init -m --yes # if new project
bun add @openai/agents-extensions @blaxel/core

python3 -m venv .venv && source .venv/bin/activate # if new project
pip install openai-agents[blaxel]

3. Configure the environment

Add your OpenAI API key, Blaxel API key and Blaxel workspace name as environment variables:

export OPENAI_API_KEY=your_key_here
export BL_API_KEY=your_key_here
export BL_WORKSPACE=your_workspace_name_here

4. Build a simple agent

In your project directory, create a file named index.ts (TypeScript) or main.py (Python) with the following code.

import { run } from "@openai/agents";
import { Manifest, SandboxAgent } from "@openai/agents/sandbox";
import { BlaxelSandboxClient } from "@openai/agents-extensions/sandbox/blaxel";

async function main() {
  const agent = new SandboxAgent({
    name: "Sandboxed agent",
    model: "gpt-5.4",
    instructions:
      "You have access to a sandbox environment. You can execute commands, manage files, and inspect processes inside the sandbox.",
    modelSettings: { toolChoice: "auto" },
    defaultManifest: new Manifest({ root: "/blaxel" }),
  });

  const client = new BlaxelSandboxClient();

  const result = await run(
    agent,
    "Install a complete Go development environment. Once done, return the installed Go version number and Go environment variables.",
    {
      maxTurns: 50,
      sandbox: {
        client,
        options: {
          name: "agent-sandbox-01",
          image: "blaxel/base-image",
          region: "us-pdx-1",
          memory: 4096,
        },
      },
    }
  );

  console.log(result.finalOutput);
}

await main().catch(console.error);

import asyncio
from agents import ModelSettings, Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.extensions.sandbox import BlaxelSandboxClient, BlaxelSandboxClientOptions

async def main():

    agent = SandboxAgent(
        name="Sandboxed agent",
        model="gpt-5.4",
        instructions=(
            "You have access to a sandbox environment. You can execute commands, manage files, and inspect processes inside the sandbox."
        ),
        model_settings=ModelSettings(tool_choice="auto"),
        default_manifest=Manifest(root="/blaxel"),
    )

    client = BlaxelSandboxClient()
    run_config = RunConfig(
        sandbox=SandboxRunConfig(
            client=client,
            options=BlaxelSandboxClientOptions(
                name="agent-sandbox-01",
                image="blaxel/base-image",
                region="us-pdx-1",
                memory=4096,
            ),
        )
    )

    result = await Runner.run(agent, "Install a complete Go development environment. Once done, return the installed Go version number and Go environment variables.", run_config=run_config)
    print(result.final_output)

    await client.close()

if __name__ == "__main__":
    asyncio.run(main())

This creates a simple sandbox-backed agent with the OpenAI Agents SDK. Instructions that you send the agent will be executed in a sandbox named agent-sandbox-01 that is dynamically created and managed in your workspace on Blaxel’s infrastructure. Run the agent. It will create and deploy a Blaxel sandbox using the blaxel/base-image image, then investigate the sandbox and install all the tools required for Go development. Once done, it will return a report of its work and automatically delete the sandbox. Here’s a partial example of the output:

Go is installed and ready.

- Installed version: `go1.25.9`
- Command check: `go version` → `go version go1.25.9 linux/amd64`

**Go Env**
- `AR='ar'`
- `CC='cc'`
- `CGO_CFLAGS='-O2 -g'`
- `CGO_CPPFLAGS=''`
- `CGO_CXXFLAGS='-O2 -g'`
- `CGO_ENABLED='1'`
- `CGO_FFLAGS='-O2 -g'`
...

5. Build a data analysis agent

In addition to running commands, agents can also create, delete and manage files and directories in the sandbox filesystem. Generated files can be transferred from the sandbox environment to the host (and vice-versa). To see this in action, update the simple agent from the previous example to perform data processing and analysis in a sandbox:

import { run } from "@openai/agents";
import { SandboxAgent } from "@openai/agents/sandbox";
import { BlaxelSandboxClient } from "@openai/agents-extensions/sandbox/blaxel";
import { writeFileSync } from "fs";

async function main() {
  const client = new BlaxelSandboxClient();
  const session = await client.create({
    options: {
      name: "agent-sandbox-02",
      image: "blaxel/py-app",
      region: "us-pdx-1",
      memory: 4096,
    },
  });

  const agent = new SandboxAgent({
    name: "Data analyst",
    model: "gpt-5.4",
    instructions:
      "You are a data analyst. You have access to a sandbox environment. You can execute commands, manage files, and inspect processes inside the sandbox.",
  });

  const stream = await run(
    agent,
    "Obtain sample telemetry data using the API https://api.datamock.dev/v1/iot-telemetry?quantity=10&deviceType=wearable_fitness_tracker&exclude=deviceId,ipAddress,macAddress,signalStrength,networkType,location,status,batteryLevel,lastSync,firmwareVersion,alerts." +
      "Analyze the received data and create a chart showing memory and CPU usage. Save it as /workspace/chart.png. " +
      "Install any packages you need.",
    {
      stream: true,
      maxTurns: 50,
      sandbox: { session },
    }
  );

  process.stdout.write("assistant> ");
  stream.toTextStream({ compatibleWithNodeStreams: true }).pipe(process.stdout);
  await stream.completed;
  process.stdout.write("\n");

  const chartData = await session.readFile({ path: "/workspace/chart.png" });
  writeFileSync("chart.png", chartData);
  console.log("Saved chart to host as chart.png");

  await session.close();
  await session.shutdown();
}

await main().catch(console.error);

import asyncio
from pathlib import Path

from openai.types.responses import ResponseTextDeltaEvent
from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from agents.extensions.sandbox import BlaxelSandboxClient, BlaxelSandboxClientOptions

async def main():
    client = BlaxelSandboxClient()
    session = await client.create(
        options=BlaxelSandboxClientOptions(
            name="agent-sandbox-02",
            image="blaxel/py-app",
            region="us-pdx-1",
            memory=4096,
        )
    )
    await session.start()

    agent = SandboxAgent(
        name="Data analyst",
        model="gpt-5.4",
        instructions="You are a data analyst. You have access to a sandbox environment. You can execute commands, manage files, and inspect processes inside the sandbox.",
    )

    stream_result = Runner.run_streamed(
        agent,
         (
            "Obtain sample telemetry data using the API https://api.datamock.dev/v1/iot-telemetry?quantity=10&deviceType=wearable_fitness_tracker&exclude=deviceId,ipAddress,macAddress,signalStrength,networkType,location,status,batteryLevel,lastSync,firmwareVersion,alerts."
            "Analyze the received data and create a chart showing memory and CPU usage. Save it as /workspace/chart.png. "
            "Install any packages you need."
         ),
        run_config=RunConfig(sandbox=SandboxRunConfig(session=session)),
        max_turns=50,
    )
    saw_text_delta = False
    async for event in stream_result.stream_events():
        if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
            if not saw_text_delta:
                print("assistant> ", end="", flush=True)
                saw_text_delta = True
            print(event.data.delta, end="", flush=True)

    if saw_text_delta:
        print()

    with open("chart.png", "wb") as f:
        f.write((await session.read(Path("/workspace/chart.png"))).read())
    print(f"Saved chart to host as chart.png")

    await session.stop()
    await session.shutdown()
    await client.close()


if __name__ == "__main__":
    asyncio.run(main())

In this example, the agent uses Blaxel’s blaxel/py-app image to create a sandbox containing a complete Python development environment. When the sandbox is created, the SDK automatically also creates a new workspace directory (defaults to /workspace but can be configured to point to another location) for the agent to operate in. The agent then uses sandbox tools to call the remote API, obtains a dataset (mock data), and autonomously installs all the required packages for chart creation. It then prepares and saves a chart of the received data to the workspace at /workspace/chart.png. This file is then read from the sandbox session and downloaded to the local host. Once the session is complete, the sandbox is terminated. Run the agent - once complete, you will have a new chart.png file in your project directory containing the generated chart. This example also demonstrates the SDK’s streaming capabilities - you will see a stream of the agent’s reasoning as it works.

6. Build a coding agent

One of the most popular uses for agents is to generate code. Sandboxes provide isolated execution environments, allowing agents to securely run generated code with no risk of escaping. Blaxel sandboxes offer a unique advantage here: human operators can preview agent-generated applications in real-time via direct preview URLs for each running sandbox. To see this in practice, update the agent code in index.ts / main.py as below:

import { run } from "@openai/agents";
import { Manifest, SandboxAgent } from "@openai/agents/sandbox";
import { urlForExposedPort } from "@openai/agents-core/sandbox";
import { BlaxelSandboxClient } from "@openai/agents-extensions/sandbox/blaxel";

async function main() {
  const task = process.argv.slice(2).join(" ").trim();
  if (!task) {
    console.log("Usage: node index.ts <task>");
    process.exit(1);
  }

  const client = new BlaxelSandboxClient();
  const session = await client.create({
    manifest: new Manifest({ root: "/blaxel" }),
    options: {
      name: "agent-sandbox-03",
      image: "blaxel/nextjs:latest",
      region: "us-pdx-1",
      memory: 4096,
      exposedPortPublic: true,
      pauseOnExit: true,
      ttl: "30m",
    },
  });

  const agent = new SandboxAgent({
    name: "Next.js code generation agent",
    model: "gpt-5.4",
    instructions:
      "You are a Next.js expert with shell access to a sandbox. You can execute commands, manage files, and start servers. The sandbox includes a skeleton Next.js app in /blaxel.",
    modelSettings: { toolChoice: "auto" },
  });

  try {
    const stream = await run(agent, task, {
      stream: true,
      maxTurns: 50,
      sandbox: { session },
    });

    process.stdout.write("assistant> ");
    stream.toTextStream({ compatibleWithNodeStreams: true }).pipe(process.stdout);
    await stream.completed;
    process.stdout.write("\n");

    const endpoint = await session.resolveExposedPort(3000);
    const previewUrl = urlForExposedPort(endpoint, "http");
    console.log(`Preview URL: ${previewUrl}`);
  } finally {
    await session.close();
    await session.shutdown();
  }
}

await main().catch(console.error);

import asyncio
import sys

from openai.types.responses import ResponseTextDeltaEvent
from agents import ModelSettings, Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.extensions.sandbox import BlaxelSandboxClient, BlaxelSandboxClientOptions


async def main():
    task = " ".join(sys.argv[1:]).strip()
    if not task:
        print("Usage: python main.py <task>")
        sys.exit(1)

    client = BlaxelSandboxClient()
    session = await client.create(
        manifest=Manifest(root="/blaxel"),
        options=BlaxelSandboxClientOptions(
            name="agent-sandbox-03",
            image="blaxel/nextjs:latest",
            region="us-pdx-1",
            memory=4096,
            exposed_port_public=True,
            pause_on_exit=True,
            ttl="30m"
        )
    )

    agent = SandboxAgent(
        name="Next.js code generation agent",
        model="gpt-5.4",
        instructions="You are a Next.js expert with shell access to a sandbox. You can execute commands, manage files, and start servers. The sandbox includes a skeleton Next.js app in /blaxel.",
        model_settings=ModelSettings(tool_choice="auto"),
    )

    try:
        stream_result = Runner.run_streamed(
            agent,
            task,
            run_config=RunConfig(sandbox=SandboxRunConfig(session=session)),
            max_turns=50,
        )
        saw_text_delta = False
        async for event in stream_result.stream_events():
            if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
                if not saw_text_delta:
                    print("assistant> ", end="", flush=True)
                    saw_text_delta = True
                print(event.data.delta, end="", flush=True)

        if saw_text_delta:
            print()

        endpoint = await session.resolve_exposed_port(3000)
        preview_url = endpoint.url_for("http")
        print(f"Preview URL: {preview_url}")
    finally:
        await session.stop()
        await session.shutdown()
        await client.close()


if __name__ == "__main__":
    asyncio.run(main())

This creates a Next.js coding agent that accepts requests from the command-line. The coding agent’s sandbox is generated from Blaxel’s blaxel/nextjs image, which contains a complete Next.js development environment and a Next.js skeleton application. Notice the ttl parameter, which sets an expiration policy to automatically delete the sandbox after 30 minutes. In addition, the exposed_port_public parameter and the resolve_exposed_port() function call take care of producing a preview URL for the user, and the pause_on_exit parameter prevents the sandbox from being automatically deleted at the end of the session. Test the agent:

# Node.js
node index.ts "My cat Kitty does amazing things. Create a website about her."

# Bun
bun index.ts "My cat Kitty does amazing things. Create a website about her."

python main.py "My cat Kitty does amazing things. Create a website about her."

The agent will start working on the task in a sandbox, streaming its responses as it works. Once it is complete, you should see a preview URL similar to the following:

Preview URL: https://a4455b03....preview.bl.run/

Open the preview URL in your browser to see the results of the agent’s work. That’s it! You’re ready to start building and deploying Blaxel sandbox-backed agents with OpenAI Agents SDK on Blaxel.

Resources

Want more info on developing and deploying agents on Blaxel? Check out the following resources:

Run OpenAI Agents SDK agents on Blaxel

You don’t have to stop at the sandboxes! Deploy OpenAI Agents SDK on Blaxel.

Deploy your agent code to Blaxel

Complete tutorial for deploying AI agents to Blaxel.

Manage environment variables

Complete tutorial for managing variables and secrets when deploying to Blaxel.

​Prerequisites

​1. Install the Blaxel CLI and log in to Blaxel

​2. Install required dependencies

​3. Configure the environment

​4. Build a simple agent

​5. Build a data analysis agent

​6. Build a coding agent

​Resources

Run OpenAI Agents SDK agents on Blaxel

Deploy your agent code to Blaxel

Manage environment variables

Prerequisites

1. Install the Blaxel CLI and log in to Blaxel

2. Install required dependencies

3. Configure the environment

4. Build a simple agent

5. Build a data analysis agent

6. Build a coding agent

Resources