Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

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,
)

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:

gllm-inference dependency removedAttachment replaced by SandboxFile
Provider SDKs extras-only — core install pulls in no backend
PydanticExecutorSandbox dropped (was deprecated)
E2B / Bedrock imports guarded, so a missing extra names itself
Layout capability-first, so computer_use/ can land beside code_interpreter/

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

gl_sandbox_binary-0.0.1b1-cp313-cp313-win_amd64.whl (577.3 kB view details)

Uploaded CPython 3.13Windows x86-64

gl_sandbox_binary-0.0.1b1-cp313-cp313-manylinux_2_31_x86_64.whl (875.6 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.31+ x86-64

gl_sandbox_binary-0.0.1b1-cp313-cp313-macosx_13_0_arm64.whl (614.4 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

gl_sandbox_binary-0.0.1b1-cp312-cp312-win_amd64.whl (579.7 kB view details)

Uploaded CPython 3.12Windows x86-64

gl_sandbox_binary-0.0.1b1-cp312-cp312-manylinux_2_31_x86_64.whl (877.1 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.31+ x86-64

gl_sandbox_binary-0.0.1b1-cp312-cp312-macosx_13_0_arm64.whl (612.9 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

gl_sandbox_binary-0.0.1b1-cp311-cp311-win_amd64.whl (598.1 kB view details)

Uploaded CPython 3.11Windows x86-64

gl_sandbox_binary-0.0.1b1-cp311-cp311-manylinux_2_31_x86_64.whl (811.0 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.31+ x86-64

gl_sandbox_binary-0.0.1b1-cp311-cp311-macosx_13_0_arm64.whl (608.7 kB view details)

Uploaded CPython 3.11macOS 13.0+ ARM64

File details

Details for the file gl_sandbox_binary-0.0.1b1-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for gl_sandbox_binary-0.0.1b1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 878d626d1795e8f0c8d3c05b81d1606bb5e64a02c6c785a73290e9629fe22b62
MD5 3d3c12bac2adbbc24e26a165a6a116e7
BLAKE2b-256 c80ebc800bcd6e4acdc48cc6f77ecd03546db887fb32bfef9807c9249b909211

See more details on using hashes here.

Provenance

The following attestation bundles were made for gl_sandbox_binary-0.0.1b1-cp313-cp313-win_amd64.whl:

Publisher: build-binary.yml on GDP-ADMIN/gl-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gl_sandbox_binary-0.0.1b1-cp313-cp313-manylinux_2_31_x86_64.whl.

File metadata

File hashes

Hashes for gl_sandbox_binary-0.0.1b1-cp313-cp313-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 f3d0926af6440c819d270b3acf0d1980639bf698c765df2a2bf3e075aac44220
MD5 c7216ecd3a9e5514e063617da20ea379
BLAKE2b-256 a5b33badcfc558c64f5f1e98dc2e7fcde342e5f9c134623f442b4541ba846623

See more details on using hashes here.

File details

Details for the file gl_sandbox_binary-0.0.1b1-cp313-cp313-macosx_13_0_arm64.whl.

File metadata

File hashes

Hashes for gl_sandbox_binary-0.0.1b1-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 77c3bcfdf8baf1ce1c5f6b51daea0285c180732132eac34bcb380e5a2cb1a202
MD5 d76afef1e49e6430f7a6e3166df60a72
BLAKE2b-256 0259e9cb258b4e6fbcc1723c0aa0b8d30cf9bf31f1a75d6590a658759f2d455c

See more details on using hashes here.

Provenance

The following attestation bundles were made for gl_sandbox_binary-0.0.1b1-cp313-cp313-macosx_13_0_arm64.whl:

Publisher: build-binary.yml on GDP-ADMIN/gl-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gl_sandbox_binary-0.0.1b1-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for gl_sandbox_binary-0.0.1b1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 dbe6bf02315c21f3efb7aea60ad0e33d40a3e7cf8423bb80751be925148c6d4f
MD5 0ea1dc12e4e0bba6e59d6a2ace6135d1
BLAKE2b-256 1468bd8f21ce9265c030f51914f3ad99d2e60db805aaf9f098a92fec4a3c161c

See more details on using hashes here.

Provenance

The following attestation bundles were made for gl_sandbox_binary-0.0.1b1-cp312-cp312-win_amd64.whl:

Publisher: build-binary.yml on GDP-ADMIN/gl-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gl_sandbox_binary-0.0.1b1-cp312-cp312-manylinux_2_31_x86_64.whl.

File metadata

File hashes

Hashes for gl_sandbox_binary-0.0.1b1-cp312-cp312-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 54940ad076f014bb6a08e88342bd523cffd20c9b259a0da8ba4f45f416f68505
MD5 aeb0b13e73b590bac19b02308f65b819
BLAKE2b-256 06a371b95bd8258d01be25d438fab82c9057a80227b78c8859f3a8e8e8c9a549

See more details on using hashes here.

File details

Details for the file gl_sandbox_binary-0.0.1b1-cp312-cp312-macosx_13_0_arm64.whl.

File metadata

File hashes

Hashes for gl_sandbox_binary-0.0.1b1-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 432ac5e9c04c57253834ef1c61cd1db4dbe2ebcbb5f60c4a1e619c509bd42527
MD5 cc6e153b2e63eae0f891039954dec961
BLAKE2b-256 cd3a2b6996fba155cab8cc9eb5d7a4ce8bd950ed2bbf9b0f80c4be882f9cb30b

See more details on using hashes here.

Provenance

The following attestation bundles were made for gl_sandbox_binary-0.0.1b1-cp312-cp312-macosx_13_0_arm64.whl:

Publisher: build-binary.yml on GDP-ADMIN/gl-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gl_sandbox_binary-0.0.1b1-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for gl_sandbox_binary-0.0.1b1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 d2e282f9580635fd8e3ac1a2790e1cc4572e97471592cc95d804f6f6ddfa3c9d
MD5 8d30519e1f7fcb13d2ec660b0f711356
BLAKE2b-256 a2bd4463719cfa1260a2fb5d390f02725ed04f9cf67aa2ae042fd92a0005abc0

See more details on using hashes here.

Provenance

The following attestation bundles were made for gl_sandbox_binary-0.0.1b1-cp311-cp311-win_amd64.whl:

Publisher: build-binary.yml on GDP-ADMIN/gl-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gl_sandbox_binary-0.0.1b1-cp311-cp311-manylinux_2_31_x86_64.whl.

File metadata

File hashes

Hashes for gl_sandbox_binary-0.0.1b1-cp311-cp311-manylinux_2_31_x86_64.whl
Algorithm Hash digest
SHA256 fbf034f0b0f4f2fb7111860e508340942e081f206b8b47c6409dd41b4ece3af1
MD5 6487095970fe8a738947651ada0436a5
BLAKE2b-256 9f7d55bd5a579277fac817dfe6de61e151ea675927e1075c6e1ac22bae140cc4

See more details on using hashes here.

File details

Details for the file gl_sandbox_binary-0.0.1b1-cp311-cp311-macosx_13_0_arm64.whl.

File metadata

File hashes

Hashes for gl_sandbox_binary-0.0.1b1-cp311-cp311-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 7479eec0cedca27e7c350d304c82d5c4404c9174b53a33fbfdcfd898c6ffb25d
MD5 caec3be826596dc004508b274b924386
BLAKE2b-256 b78894cdd883eb8888296ae4d6eedb2eefc872c6aaeaf1ce0f46c03c167c13a4

See more details on using hashes here.

Provenance

The following attestation bundles were made for gl_sandbox_binary-0.0.1b1-cp311-cp311-macosx_13_0_arm64.whl:

Publisher: build-binary.yml on GDP-ADMIN/gl-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page