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 |
removed — Attachment 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
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file gl_sandbox_binary-0.0.1b1-cp313-cp313-win_amd64.whl.
File metadata
- Download URL: gl_sandbox_binary-0.0.1b1-cp313-cp313-win_amd64.whl
- Upload date:
- Size: 577.3 kB
- Tags: CPython 3.13, Windows x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
878d626d1795e8f0c8d3c05b81d1606bb5e64a02c6c785a73290e9629fe22b62
|
|
| MD5 |
3d3c12bac2adbbc24e26a165a6a116e7
|
|
| BLAKE2b-256 |
c80ebc800bcd6e4acdc48cc6f77ecd03546db887fb32bfef9807c9249b909211
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
gl_sandbox_binary-0.0.1b1-cp313-cp313-win_amd64.whl -
Subject digest:
878d626d1795e8f0c8d3c05b81d1606bb5e64a02c6c785a73290e9629fe22b62 - Sigstore transparency entry: 2406425108
- Sigstore integration time:
-
Permalink:
GDP-ADMIN/gl-sdk@b90e11853dcd39a8a8e156200aca5e6721579eea -
Branch / Tag:
refs/tags/gl_sandbox-v0.0.1b1 - Owner: https://github.com/GDP-ADMIN
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
build-binary.yml@b90e11853dcd39a8a8e156200aca5e6721579eea -
Trigger Event:
push
-
Statement type:
File details
Details for the file gl_sandbox_binary-0.0.1b1-cp313-cp313-manylinux_2_31_x86_64.whl.
File metadata
- Download URL: gl_sandbox_binary-0.0.1b1-cp313-cp313-manylinux_2_31_x86_64.whl
- Upload date:
- Size: 875.6 kB
- Tags: CPython 3.13, manylinux: glibc 2.31+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.8.24
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f3d0926af6440c819d270b3acf0d1980639bf698c765df2a2bf3e075aac44220
|
|
| MD5 |
c7216ecd3a9e5514e063617da20ea379
|
|
| BLAKE2b-256 |
a5b33badcfc558c64f5f1e98dc2e7fcde342e5f9c134623f442b4541ba846623
|
File details
Details for the file gl_sandbox_binary-0.0.1b1-cp313-cp313-macosx_13_0_arm64.whl.
File metadata
- Download URL: gl_sandbox_binary-0.0.1b1-cp313-cp313-macosx_13_0_arm64.whl
- Upload date:
- Size: 614.4 kB
- Tags: CPython 3.13, macOS 13.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
77c3bcfdf8baf1ce1c5f6b51daea0285c180732132eac34bcb380e5a2cb1a202
|
|
| MD5 |
d76afef1e49e6430f7a6e3166df60a72
|
|
| BLAKE2b-256 |
0259e9cb258b4e6fbcc1723c0aa0b8d30cf9bf31f1a75d6590a658759f2d455c
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
gl_sandbox_binary-0.0.1b1-cp313-cp313-macosx_13_0_arm64.whl -
Subject digest:
77c3bcfdf8baf1ce1c5f6b51daea0285c180732132eac34bcb380e5a2cb1a202 - Sigstore transparency entry: 2406424577
- Sigstore integration time:
-
Permalink:
GDP-ADMIN/gl-sdk@b90e11853dcd39a8a8e156200aca5e6721579eea -
Branch / Tag:
refs/tags/gl_sandbox-v0.0.1b1 - Owner: https://github.com/GDP-ADMIN
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
build-binary.yml@b90e11853dcd39a8a8e156200aca5e6721579eea -
Trigger Event:
push
-
Statement type:
File details
Details for the file gl_sandbox_binary-0.0.1b1-cp312-cp312-win_amd64.whl.
File metadata
- Download URL: gl_sandbox_binary-0.0.1b1-cp312-cp312-win_amd64.whl
- Upload date:
- Size: 579.7 kB
- Tags: CPython 3.12, Windows x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
dbe6bf02315c21f3efb7aea60ad0e33d40a3e7cf8423bb80751be925148c6d4f
|
|
| MD5 |
0ea1dc12e4e0bba6e59d6a2ace6135d1
|
|
| BLAKE2b-256 |
1468bd8f21ce9265c030f51914f3ad99d2e60db805aaf9f098a92fec4a3c161c
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
gl_sandbox_binary-0.0.1b1-cp312-cp312-win_amd64.whl -
Subject digest:
dbe6bf02315c21f3efb7aea60ad0e33d40a3e7cf8423bb80751be925148c6d4f - Sigstore transparency entry: 2406425050
- Sigstore integration time:
-
Permalink:
GDP-ADMIN/gl-sdk@b90e11853dcd39a8a8e156200aca5e6721579eea -
Branch / Tag:
refs/tags/gl_sandbox-v0.0.1b1 - Owner: https://github.com/GDP-ADMIN
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
build-binary.yml@b90e11853dcd39a8a8e156200aca5e6721579eea -
Trigger Event:
push
-
Statement type:
File details
Details for the file gl_sandbox_binary-0.0.1b1-cp312-cp312-manylinux_2_31_x86_64.whl.
File metadata
- Download URL: gl_sandbox_binary-0.0.1b1-cp312-cp312-manylinux_2_31_x86_64.whl
- Upload date:
- Size: 877.1 kB
- Tags: CPython 3.12, manylinux: glibc 2.31+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.8.24
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
54940ad076f014bb6a08e88342bd523cffd20c9b259a0da8ba4f45f416f68505
|
|
| MD5 |
aeb0b13e73b590bac19b02308f65b819
|
|
| BLAKE2b-256 |
06a371b95bd8258d01be25d438fab82c9057a80227b78c8859f3a8e8e8c9a549
|
File details
Details for the file gl_sandbox_binary-0.0.1b1-cp312-cp312-macosx_13_0_arm64.whl.
File metadata
- Download URL: gl_sandbox_binary-0.0.1b1-cp312-cp312-macosx_13_0_arm64.whl
- Upload date:
- Size: 612.9 kB
- Tags: CPython 3.12, macOS 13.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
432ac5e9c04c57253834ef1c61cd1db4dbe2ebcbb5f60c4a1e619c509bd42527
|
|
| MD5 |
cc6e153b2e63eae0f891039954dec961
|
|
| BLAKE2b-256 |
cd3a2b6996fba155cab8cc9eb5d7a4ce8bd950ed2bbf9b0f80c4be882f9cb30b
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
gl_sandbox_binary-0.0.1b1-cp312-cp312-macosx_13_0_arm64.whl -
Subject digest:
432ac5e9c04c57253834ef1c61cd1db4dbe2ebcbb5f60c4a1e619c509bd42527 - Sigstore transparency entry: 2406424574
- Sigstore integration time:
-
Permalink:
GDP-ADMIN/gl-sdk@b90e11853dcd39a8a8e156200aca5e6721579eea -
Branch / Tag:
refs/tags/gl_sandbox-v0.0.1b1 - Owner: https://github.com/GDP-ADMIN
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
build-binary.yml@b90e11853dcd39a8a8e156200aca5e6721579eea -
Trigger Event:
push
-
Statement type:
File details
Details for the file gl_sandbox_binary-0.0.1b1-cp311-cp311-win_amd64.whl.
File metadata
- Download URL: gl_sandbox_binary-0.0.1b1-cp311-cp311-win_amd64.whl
- Upload date:
- Size: 598.1 kB
- Tags: CPython 3.11, Windows x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d2e282f9580635fd8e3ac1a2790e1cc4572e97471592cc95d804f6f6ddfa3c9d
|
|
| MD5 |
8d30519e1f7fcb13d2ec660b0f711356
|
|
| BLAKE2b-256 |
a2bd4463719cfa1260a2fb5d390f02725ed04f9cf67aa2ae042fd92a0005abc0
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
gl_sandbox_binary-0.0.1b1-cp311-cp311-win_amd64.whl -
Subject digest:
d2e282f9580635fd8e3ac1a2790e1cc4572e97471592cc95d804f6f6ddfa3c9d - Sigstore transparency entry: 2406424471
- Sigstore integration time:
-
Permalink:
GDP-ADMIN/gl-sdk@b90e11853dcd39a8a8e156200aca5e6721579eea -
Branch / Tag:
refs/tags/gl_sandbox-v0.0.1b1 - Owner: https://github.com/GDP-ADMIN
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
build-binary.yml@b90e11853dcd39a8a8e156200aca5e6721579eea -
Trigger Event:
push
-
Statement type:
File details
Details for the file gl_sandbox_binary-0.0.1b1-cp311-cp311-manylinux_2_31_x86_64.whl.
File metadata
- Download URL: gl_sandbox_binary-0.0.1b1-cp311-cp311-manylinux_2_31_x86_64.whl
- Upload date:
- Size: 811.0 kB
- Tags: CPython 3.11, manylinux: glibc 2.31+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.8.24
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fbf034f0b0f4f2fb7111860e508340942e081f206b8b47c6409dd41b4ece3af1
|
|
| MD5 |
6487095970fe8a738947651ada0436a5
|
|
| BLAKE2b-256 |
9f7d55bd5a579277fac817dfe6de61e151ea675927e1075c6e1ac22bae140cc4
|
File details
Details for the file gl_sandbox_binary-0.0.1b1-cp311-cp311-macosx_13_0_arm64.whl.
File metadata
- Download URL: gl_sandbox_binary-0.0.1b1-cp311-cp311-macosx_13_0_arm64.whl
- Upload date:
- Size: 608.7 kB
- Tags: CPython 3.11, macOS 13.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7479eec0cedca27e7c350d304c82d5c4404c9174b53a33fbfdcfd898c6ffb25d
|
|
| MD5 |
caec3be826596dc004508b274b924386
|
|
| BLAKE2b-256 |
b78894cdd883eb8888296ae4d6eedb2eefc872c6aaeaf1ce0f46c03c167c13a4
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
gl_sandbox_binary-0.0.1b1-cp311-cp311-macosx_13_0_arm64.whl -
Subject digest:
7479eec0cedca27e7c350d304c82d5c4404c9174b53a33fbfdcfd898c6ffb25d - Sigstore transparency entry: 2406425124
- Sigstore integration time:
-
Permalink:
GDP-ADMIN/gl-sdk@b90e11853dcd39a8a8e156200aca5e6721579eea -
Branch / Tag:
refs/tags/gl_sandbox-v0.0.1b1 - Owner: https://github.com/GDP-ADMIN
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
build-binary.yml@b90e11853dcd39a8a8e156200aca5e6721579eea -
Trigger Event:
push
-
Statement type: