Sandboxes for the OpenAI Agents SDK

Set up the agent VM#

Deploy sets it up on a new VM. To do it yourself:

ssh exe.dev new --name=my-openai-agents
ssh my-openai-agents.exe.xyz

mkdir -p ~/openai-agents && cd ~/openai-agents
curl -fsSLO https://exe-staging.dev/deploy/openai-agents-sdk/agent.py
curl -fsSLO https://exe-staging.dev/deploy/openai-agents-sdk/exe_sandbox.py
chmod +x agent.py

Let it make VMs#

The agent VM makes session VMs through exe.dev's API, by way of an integration that holds the API key: no key is ever on a VM. On your computer:

ssh exe.dev integrations add exe-dev --name openai-agents \
  --tag openai-sandbox --cmds new,ls,ssh,rm --attach vm:my-openai-agents

The integration can make, reach, and delete VMs tagged openai-sandbox, and nothing else; the VMs it makes get that tag. Only the agent VM can use it. ssh exe.dev integrations remove openai-agents revokes it.

On the agent VM, check it:

curl -s -X POST https://openai-agents.int.exe.xyz/exec -d ls

Expect {"vms":[]}. Then give it a first task, in ~/openai-agents. uv installs the SDK the first time:

./agent.py "Write the output of hostname to hello.txt, and show it to me."

Expect session <name>, on VM <name>, a line for each command or edit the agent makes, and a reply with the session VM's name, which is not this VM's.

Give it a task#

On the agent VM, in ~/openai-agents:

./agent.py "Make a small Flask to-do app, serve it on port 8080, and give me the link."

The agent gets a new VM, and each command it runs shows up as it runs. The link it gives, https://<session-vm>.exe.xyz:8080/, opens for you after exe.dev login, like any port from 3000 to 9999 through the HTTPS proxy.

Each session keeps its VM, its conversation, and its files. Continue it with the name it printed:

./agent.py -s <name> "Add a due date to each to-do."

./agent.py --ls lists sessions, and ./agent.py --rm <name> deletes one and its VM. You can also open a session's VM yourself, on your computer: ssh <name>.exe.xyz, then cd /workspace.

Warning

The agent runs commands with sudo, without asking. That's what the session VMs are for: they hold nothing else. Keep the agent VM, which can make VMs on your account, to yourself, and never attach the integration to the openai-sandbox tag, which would let sessions do the same.

Use it in your own code#

exe_sandbox.py works with any SandboxAgent. Put it beside your code on the agent VM, and pass the client in SandboxRunConfig. This agent starts with a repository checked out on its VM:

import asyncio

from agents import Runner, set_default_openai_client, set_tracing_disabled
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import GitRepo
from openai import AsyncOpenAI

from exe_sandbox import ExeSandboxClient, ExeSandboxClientOptions

# On an exe.dev VM, models come from the LLM integration; the key is a placeholder.
set_default_openai_client(AsyncOpenAI(base_url="https://llm.int.exe.xyz/v1", api_key="exe.dev"), use_for_tracing=False)
set_tracing_disabled(True)

agent = SandboxAgent(
    name="Reviewer",
    model="gpt-6.1-sol",
    instructions="Answer questions about the repository in repo/. Run commands to check.",
    default_manifest=Manifest(entries={"repo": GitRepo(repo="openai/openai-agents-python", ref="main")}),
)

async def main():
    result = await Runner.run(
        agent,
        "Which sandbox providers are under repo/src/agents/extensions?",
        run_config=RunConfig(sandbox=SandboxRunConfig(
            client=ExeSandboxClient(api="https://openai-agents.int.exe.xyz"),
            options=ExeSandboxClientOptions(cpu=2))),
    )
    print(result.final_output)

asyncio.run(main())

Run it with uv run --with 'openai-agents>=0.24,<0.25' --with 'exedev>=0.4,<0.5' review.py. When the run ends, the SDK closes the session and its VM is deleted. ExeSandboxClientOptions also takes memory, disk, image, egress, integrations, tags, comment, exposed_ports, and on_exit:

• on_exit="keep" keeps the VM. Save the session's state with client.serialize_session_state(session.state), and client.resume(...) reconnects to the same VM later, with its files, packages, and running services. That's how agent.py keeps sessions.
• If a kept VM is gone, resuming makes a new, empty one. To bring the files back too, create the session with a snapshot, such as snapshot=LocalSnapshotSpec(base_path=Path("snapshots")): the SDK saves /workspace when the session closes and restores it onto the new VM.
• For work the SDK has no method for, session.vm is the exe.dev VM object (await session.vm.run("...")).

Off exe.dev, integrations aren't reachable. Use ExeSandboxClient(token=...) with an exe.dev API key from ssh exe.dev ssh-key generate-api-key --label=openai-agents --tag=openai-sandbox --cmds=new,ls,ssh,rm --exp=30d, leave out the two set_ lines, and set OPENAI_API_KEY.

Or let OpenAI run the agent#

OpenAI's Agents API (in beta) turns this around: OpenAI runs the agent loop, the Codex harness, and a self-hosted environment runs its tools wherever you start codex exec-server. Codex is already on every exe.dev VM, so a VM per session takes one more short program: agents_api.py creates a session, makes its VM through the same integration, and starts codex exec-server there under systemd.

It needs two OpenAI keys, which the LLM integration doesn't replace:

• An OpenAI API key with api.agents.read, api.agents.write, and api.responses.write. Keep it off the VM in an HTTP proxy integration. On your computer:

  printf %s "$OPENAI_API_KEY" | ssh exe.dev integrations add http-proxy --name openai \
    --target https://api.openai.com --bearer=- --attach vm:my-openai-agents
  

• An environment key, from the Agents tab of the OpenAI platform, with every other permission set to None. It can only connect environments, and each session VM gets a copy, as OpenAI's design has it.

On the agent VM, fill in the environment key:

cd ~/openai-agents
curl -fsSLO https://exe-staging.dev/deploy/openai-agents-sdk/agents_api.py
chmod +x agents_api.py
(umask 077; echo 'OPENAI_EXECUTOR_API_KEY=...' >> .env)
./agents_api.py "Write the output of hostname to hello.txt, and show it to me."

Expect session sess_..., on VM <name>, then the agent's reply with that VM's name. ./agents_api.py -s sess_... "..." continues a session on its VM, restarting the executor if the VM was rebooted, and ./agents_api.py --rm sess_... deletes the session and its VM. OpenAI bills the model at its API rates; MODEL in .env picks it (default gpt-6-astra).

Clean up#

./agent.py --rm <name> deletes a session. On your computer, ssh exe.dev ls lists session VMs with their task as the comment. To delete every VM tagged openai-sandbox, including any the agent VM's sessions still use (its first two lines alone list them):

ssh exe.dev ls --json |
  jq -r '.vms[] | select(.tags // [] | index("openai-sandbox")) | .vm_name' |
  xargs -r ssh exe.dev rm

Session history is in ~/openai-agents/sessions on the agent VM. When you're done with it all, ssh exe.dev integrations remove openai-agents.

Troubleshooting#

• exe.dev API error (403) during new: integration not found or not attached to this VM: run the command in Let it make VMs with this VM's name, or ssh exe.dev integrations attach openai-agents vm:<this-vm>.
• agents_api.py stops with 403 and integration not found: attach the openai integration to this VM, as in Or let OpenAI run the agent.
• during new: ... otherwise: exe.dev refused a VM, often because the plan's VM limit is reached. Delete old sessions.
• Connection error from the model: the LLM integration is reachable only from exe.dev VMs. Elsewhere, set OPENAI_API_KEY.
• A command that starts a server with & and leaves it writing to the terminal holds the command open until it times out. Run servers under sudo systemd-run, as agent.py tells the model to.