gl-sandbox

Provider-agnostic sandbox SDK: run untrusted code, ship files in and out, and build reusable sandbox images — across E2B, OpenSandbox and AWS Bedrock AgentCore behind one interface.

Installation

The core install is provider-free — it pulls in no backend SDK. Pick the backends you need:

pip install gl-sandbox                    # ABCs, models, errors, tracing — no backend
pip install 'gl-sandbox[e2b]'             # + E2B
pip install 'gl-sandbox[opensandbox]'     # + OpenSandbox
pip install 'gl-sandbox[bedrock]'         # + AWS Bedrock AgentCore
pip install 'gl-sandbox[all]'             # + everything

Importing a backend module without its extra raises an ImportError naming the extra to install.

Layout

The package is organized capability-first: a provider-agnostic root, then one package per capability, then one module per provider inside it.

gl_sandbox/
├── base.py              BaseSandbox — provider- and capability-agnostic lifecycle
├── models.py            ExecutionResult, ExecutionStatus, SandboxFile
├── errors.py            Stage-attributed error taxonomy
├── observability.py     Optional OpenTelemetry spans (no-op when OTel is absent)
├── constants.py         Shared defaults
├── utils.py             Install-code generation, timeout resolution, retry wrappers
├── providers/           Provider-scoped helpers shared across capabilities
│   └── opensandbox/
│       └── snapshot.py    Snapshot name → id resolution      [opensandbox]
├── code_interpreter/    Capability: run code
│   ├── base.py            CodeInterpreterSandbox
│   ├── e2b.py             E2BSandbox                  [e2b]
│   ├── opensandbox.py     OpenSandbox                 [opensandbox]
│   └── bedrock.py         BedrockAgentCoreSandbox     [bedrock]
├── computer_use/        Capability: reserved for the desktop-automation axis
└── template/            Build sandbox images / templates / snapshots
    ├── base.py            BaseTemplateBuilder
    ├── e2b.py             E2BTemplateBuilder          [e2b]
    ├── opensandbox.py     OpenSandboxTemplateBuilder  [opensandbox]
    └── bedrock.py         BedrockTemplateBuilder      (no extra needed — no build step)

Backends live in their own modules, by design. gl_sandbox, gl_sandbox.code_interpreter and gl_sandbox.template export only ABCs, models and errors, so importing them pulls in no provider SDK. Import a concrete backend from its own module:

from gl_sandbox.code_interpreter.e2b import E2BSandbox  # not from gl_sandbox

Usage

Run code in a sandbox

import asyncio

from gl_sandbox import ExecutionStatus
from gl_sandbox.code_interpreter.e2b import E2BSandbox


async def main() -> None:
    sandbox = await E2BSandbox.create(api_key="e2b_...", additional_packages=["numpy"])
    try:
        result = await sandbox.execute_code("import numpy; print(numpy.__version__)")
        if result.status is ExecutionStatus.SUCCESS:
            print(result.stdout)
        else:
            print(result.error)
    finally:
        await sandbox.terminate()


asyncio.run(main())

Upload files, then run against them

SandboxFile is gl-sandbox's own two-field DTO, so nothing here depends on an inference library. Any structurally compatible object (.filename + .data) is accepted, including gllm_inference.schema.Attachment.

from gl_sandbox import SandboxFile

files = [SandboxFile.from_bytes(b"a,b\n1,2\n", "data.csv")]
result = await sandbox.execute_code(
    "import pandas as pd; print(pd.read_csv('/files/data.csv'))",
    files=files,
)

Write workspace files and run commands safely

Workspace primitives provide one bounded contract across E2B, OpenSandbox, and Bedrock AgentCore for durable files and exact-argv execution:

from gl_sandbox import WorkspaceFileWriteRequest
from gl_sandbox.code_interpreter import run_workspace_command, write_workspace_file

await write_workspace_file(
    sandbox,
    WorkspaceFileWriteRequest(
        relative_path="reports/result.json",
        data=b'{"ok": true}',
        max_bytes=16 * 1024 * 1024,
        overwrite=True,
    ),
)
result = await run_workspace_command(
    sandbox,
    ["python", "tools/report.py", "--output", "reports/result.json"],
    cwd_components=("reports",),
    env={"PYTHONUNBUFFERED": "1"},
    env_allowlist=("HOME",),
    timeout=30,
    max_output_bytes=1024 * 1024,
)

Writes reject absolute paths, traversal, symlinks, oversized payloads, and unauthorized replacement. Commands receive an exact argv vector without shell interpolation, run in a confined directory with an allowlisted environment, and return bounded output with observed byte counts, completeness, and truncation flags. Counts are exact when the corresponding *_byte_count_complete flag is true; a provider that leaves a pipe open after bounded timeout cleanup reports false rather than claiming completeness. The default empty env_allowlist deliberately omits PATH; non-absolute executables are still resolved with Python's os.defpath fallback. Allowlist PATH explicitly when a command needs a custom search path. None means the 30-second package default for command timeouts, while <= 0 disables the inner deadline. The write primitive disables the provider code-channel timeout because the bounded write itself has no separate timeout parameter. Cancellation terminates the sandbox; callers must discard it and create a new session before issuing more work. Confinement fails closed when the runner lacks the required descriptor/procfs features or the Linux openat2/Landlock kernel enforcement used by the command helper. Each file write runs in a fresh exec-launched helper, where Landlock is installed immediately before mutation; persistent provider code kernels are never restricted. Linux file writes require Landlock ABI 3 (the REFER and TRUNCATE rights) and fail closed on older or unsupported kernels. Process setup is performed without preexec_fn, so threaded providers do not inherit fork-time Python callbacks.

Build a template once, create sandboxes from it

from gl_sandbox.template import TemplateSpec
from gl_sandbox.template.e2b import E2BTemplateBuilder

builder = E2BTemplateBuilder(api_key="e2b_...")
result = await builder.ensure(TemplateSpec(name="my-base", packages=["pandas", "numpy"]))
sandbox = await E2BSandbox.create(api_key="e2b_...", template=result.ref.template_id)

Errors carry the stage that failed

Every exception records the Stage at its raise site and exposes transient, so retry logic and user-facing messages never drift apart.

from gl_sandbox import SandboxStartError, Stage

try:
    sandbox = await E2BSandbox.create(api_key="e2b_...")
except SandboxStartError as exc:
    if exc.stage is Stage.CREATE and exc.transient:
        ...  # worth retrying

Tracing

observability.py emits OpenTelemetry spans under the gl_sandbox.* namespace against whatever tracer provider the host application configured. It is fully optional: with OpenTelemetry absent, every helper degrades to a no-op, and gl-sandbox takes no dependency on it.

Development

make setup             # uv + pre-commit + dependencies
make test              # unit tests with coverage (needs --all-extras; see below)
make test-core         # import smoke test: core install must work with no extras
make test-integration  # live, credential-gated tests that provision real sandboxes
make ruff              # lint + format check

Unit tests require --all-extras: only the OpenSandbox SDK is stubbed in conftest.py, while the E2B and Bedrock tests import their SDKs for real. Integration tests are excluded by default via addopts = "-m 'not integration'" and each self-skips without its credentials.

Relationship to gllm-tools

This library was extracted from gllm-tools (gllm_tools/code_interpreter/) as a 1:1 copy. gllm-tools retains its own copy and is unaffected; the two have not yet been deduplicated.

Deliberate differences from the origin:

Everything the port deliberately did not clean up is catalogued in docs/TECHNICAL-DEBT.md — 29 open items ranked by severity, plus the invariants that look like bugs and must be preserved.