openai-agents-groundbox
Run OpenAI Agents SDK sandbox agents on
Groundbox: a Linux microVM (Firecracker) with its own cores for each
agent session. GroundboxSandboxClient is a sandbox client in the same shape as the SDK's own
E2B, Modal and Daytona extensions; pass it to SandboxRunConfig.
Install
pip install openai-agents-groundbox
Set GROUNDBOX_API_KEY (create one at https://app.groundbox.dev/keys, or let an agent sign
itself up for a free trial: npx -y @groundbox/cli signup --name my-agent).
Tested with openai-agents 0.25.0 and groundbox 0.4.2, Python 3.10 or newer.
Use it
import asyncio
from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.capabilities import Shell
from agents.sandbox.entries import File
from openai_agents_groundbox import GroundboxSandboxClient, GroundboxSandboxClientOptions
agent = SandboxAgent(
name="Workspace assistant",
instructions="Answer questions about the workspace. Inspect the files first.",
default_manifest=Manifest(entries={"notes.md": File(content=b"# Notes\n\nShip on Friday.\n")}),
capabilities=[Shell()],
)
run_config = RunConfig(
sandbox=SandboxRunConfig(
client=GroundboxSandboxClient(), # reads GROUNDBOX_API_KEY
options=GroundboxSandboxClientOptions(cpus=2, timeout_minutes=30),
),
)
result = asyncio.run(Runner.run(agent, "When do we ship?", run_config=run_config))
print(result.final_output)
The runner creates the sandbox, writes the manifest into the workspace
(/home/runner/workspace by default), runs the agent's shell and file tools in it, and
deletes the sandbox when the run ends.
To keep one sandbox across several runs, create the session yourself and pass it in:
client = GroundboxSandboxClient()
session = await client.create(manifest=agent.default_manifest, options=GroundboxSandboxClientOptions())
async with session:
await Runner.run(agent, "First question", run_config=RunConfig(sandbox=SandboxRunConfig(session=session)))
await Runner.run(agent, "Second question", run_config=RunConfig(sandbox=SandboxRunConfig(session=session)))
await client.delete(session)
examples/run_agent.py is a complete script (it needs OPENAI_API_KEY too; --scripted
runs it with a scripted model instead, no model key).
Options
GroundboxSandboxClientOptions maps to POST /v1/sandboxes. Everything is optional:
| Option | What it does |
|---|---|
cpus, memory_gb, disk_gb |
Size: 1 to 16 vCPUs, up to 4 GB per vCPU (default 2 vCPUs, 2 GB per vCPU, 20 GB disk) |
timeout_minutes, on_timeout |
When the sandbox ends (default 60 minutes) and what that does: delete, stop or pause |
image |
Start from a Docker image, e.g. python:3.12-slim (commands run as root) |
template |
Start from a Groundbox template |
env, secrets |
Environment variables, and team secrets given as variables |
metadata |
Labels on the sandbox (the session id is added as openai_agents_session) |
allow_hosts, deny_hosts |
Egress allowlist or deny list |
flex |
Half price, starts when a machine has spare room |
idle_timeout_seconds |
Pause the sandbox when idle; the next call wakes it |
pause_on_exit |
Pause instead of delete when the session shuts down, so client.resume(state) reattaches |
workspace_persistence |
"tar" (default) or "snapshot", see below |
exposed_ports, public_ports |
Ports session.resolve_exposed_port(port) gives an HTTPS address |
timeouts |
GroundboxSandboxTimeouts for exec, create, tar and PTY hang-up |
The client takes api_key and base_url (or GROUNDBOX_API_KEY / GROUNDBOX_API_URL), or a
ready groundbox=Groundbox(...) client. client.groundbox is that client, for anything this
interface does not cover (fork, save points, egress changes while running).
What works
- Commands (
exec), with the manifest's environment, the workspace root as the working directory, timeouts, anduser=(run throughsudo -u; the default image'srunneruser has sudo). A command with no timeout gets an hour (GroundboxSandboxTimeouts.exec_timeout_unbounded_s); commands allowed longer than an hour run in the background and are polled. - A workspace root outside the user's home (the SDK's default
Manifest()root is/workspace) is made with sudo and given to therunneruser. - PTY sessions for the
exec_command/write_stdintools, over Groundbox's command stream.tty=Truegives a terminal that takes input; a long command without a tty keeps running and is read on later. Commands are resumable, so a dropped connection reattaches. - Files: read, write, mkdir through the Groundbox files API; ls, rm, mv and
apply_patchthrough the SDK's shell fallbacks. Paths are confined to the workspace like the other remote backends. - Persistence on
stop():"tar"archives the workspace root and restores it into a new sandbox on resume."snapshot"keeps a Groundbox snapshot of the whole sandbox (memory, disk and processes) and starts the resumed sandbox from it (paid plan). Eachstop()keeps a new snapshot, labelledopenai-agents <session id>; the package does not delete old ones. Snapshots unused for a month expire, a team keeps up to 50, andclient.groundbox.delete_snapshot(id)deletes one. - Resume:
client.resume(state)reattaches to the same sandbox when it still exists (running, paused, or stopped with its disk kept), otherwise it makes a new one from the saved options and restores the workspace snapshot. - Exposed ports through Groundbox previews (paid plan). Private ports resolve to a share link
whose token is in
ExposedPortEndpoint.query(valid 24 hours);public_ports=Truemakes them public.
Limits
- Cloud bucket mounts (S3, R2, GCS, Azure) have no Groundbox mount strategy and are untested.
- PTY output arrives as text: bytes that are not UTF-8 are replaced. Non-PTY
execreturns output byte for byte. - The first sandbox from a Docker
imagewaits while the image is turned into a disk (up to a few minutes);GroundboxSandboxTimeouts.create_sbounds that wait. - The free trial allows 2 sandboxes at a time, 2 vCPUs, 4 GB and 60 minutes each;
stop/pauseon timeout, kept snapshots and previews need the paid plan. - The package uses the SDK's underscored session hooks, so it pins
openai-agentsto the 0.25 series.
Tests
pip install -e ".[test]"
pytest -m "not live" # unit tests, with a fake Groundbox API
GROUNDBOX_API_KEY=gbx_... pytest -m live # against the real API: creates and deletes sandboxes
The unit tests run their commands with the local shell (GNU tools; they are run on Linux).
The live tests need no model key: the Runner test uses the SDK's ScriptedModel, so it
drives the real Runner → SandboxRunConfig → Groundbox path without calling a model.
License
MIT. See the repository's LICENSE.
Metadata
Release files for openai-agents-groundbox 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openai_agents_groundbox-0.1.0.tar.gz | 26.0 kB | Without provenance | Details for openai_agents_groundbox-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openai_agents_groundbox-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for openai_agents_groundbox-0.1.0-py3-none-any.whl |
Total release size: 43.8 kB
Release files / openai_agents_groundbox-0.1.0.tar.gz
| Download URL | openai_agents_groundbox-0.1.0.tar.gz |
|---|---|
| Size | 26.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2cc48d45d4af46662e71c6f7f3c373f6272383f39f337f3dd62624add475c199
|
|
BLAKE2b-256 checksum How to use checksums |
15fff818a2192857393df4dd9a1a32969c6d3b1ef40ce99d396a1abfc248c239
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Release files / openai_agents_groundbox-0.1.0-py3-none-any.whl
| Download URL | openai_agents_groundbox-0.1.0-py3-none-any.whl |
|---|---|
| Size | 17.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6d0aa83d4548befade0ddf2841317ad548fd8eef166b36c707758c156b90c995
|
|
BLAKE2b-256 checksum How to use checksums |
f5a753d6a7e36a0fd09e677f46c348edf29b79d84c43f98dd66288045ccb7db6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Security for openai-agents-groundbox 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.