Skip to main content
Incomplete provenance

3 of 9 release files were uploaded without provenance metadata. View details.

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

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:

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.

Metadata

Release files for gl-sandbox-binary 0.0.1b4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Incomplete provenance

3 of 9 files were uploaded without provenance metadata.

We recommend further investigation before installing these files. View details.

Built distributions (wheels)

Table of built distributions (wheels) for gl-sandbox-binary 0.0.1b4
File Actions
gl_sandbox_binary-0.0.1b4-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details for gl_sandbox_binary-0.0.1b4-cp313-cp313-win_amd64.whl
gl_sandbox_binary-0.0.1b4-cp313-cp313-manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.28+ x86-64 Details for gl_sandbox_binary-0.0.1b4-cp313-cp313-manylinux_2_28_x86_64.whl
gl_sandbox_binary-0.0.1b4-cp313-cp313-macosx_13_0_arm64.whl CPython 3.13 CPython 3.13 macOS 13.0+ ARM64 Details for gl_sandbox_binary-0.0.1b4-cp313-cp313-macosx_13_0_arm64.whl
gl_sandbox_binary-0.0.1b4-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for gl_sandbox_binary-0.0.1b4-cp312-cp312-win_amd64.whl
gl_sandbox_binary-0.0.1b4-cp312-cp312-manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64 Details for gl_sandbox_binary-0.0.1b4-cp312-cp312-manylinux_2_28_x86_64.whl
gl_sandbox_binary-0.0.1b4-cp312-cp312-macosx_13_0_arm64.whl CPython 3.12 CPython 3.12 macOS 13.0+ ARM64 Details for gl_sandbox_binary-0.0.1b4-cp312-cp312-macosx_13_0_arm64.whl
gl_sandbox_binary-0.0.1b4-cp311-cp311-win_amd64.whl CPython 3.11 CPython 3.11 Windows x86-64 Details for gl_sandbox_binary-0.0.1b4-cp311-cp311-win_amd64.whl
gl_sandbox_binary-0.0.1b4-cp311-cp311-manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64 Details for gl_sandbox_binary-0.0.1b4-cp311-cp311-manylinux_2_28_x86_64.whl
gl_sandbox_binary-0.0.1b4-cp311-cp311-macosx_13_0_arm64.whl CPython 3.11 CPython 3.11 macOS 13.0+ ARM64 Details for gl_sandbox_binary-0.0.1b4-cp311-cp311-macosx_13_0_arm64.whl

Total release size: 7.4 MB

Release files / gl_sandbox_binary-0.0.1b4-cp313-cp313-win_amd64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL gl_sandbox_binary-0.0.1b4-cp313-cp313-win_amd64.whl
Size 688.8 kB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
e59f8f582560ad7e01c4e986941e2db3a460cd234254521f8a2380ed2d44a1be
BLAKE2b-256 checksum
How to use checksums
b1213e23ba0b24896c122ee5ddb649caac9670a829e5f0942e5296434eddadcb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / gl_sandbox_binary-0.0.1b4-cp313-cp313-manylinux_2_28_x86_64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while other files in this release have provenance metadata, this file does not.

We recommend further investigation before installing this file. View details.

Download URL gl_sandbox_binary-0.0.1b4-cp313-cp313-manylinux_2_28_x86_64.whl
Size 1.1 MB
Tags CPython 3.13 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
484b0c9cd4d3735f1f7a5718e87ffa732757b652ea8c61aa90b7a05de472530e
BLAKE2b-256 checksum
How to use checksums
1a8062d0b647ff6ff753b85f0322c8014349d9e8cbccc2890ed46b5d43105c3b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"AlmaLinux","version":"8.10","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / gl_sandbox_binary-0.0.1b4-cp313-cp313-macosx_13_0_arm64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL gl_sandbox_binary-0.0.1b4-cp313-cp313-macosx_13_0_arm64.whl
Size 761.2 kB
Tags CPython 3.13 macOS 13.0+ ARM64
SHA-256 checksum
How to use checksums
18a0a881def060cca83db9084ccdce65c4a05c63788d9dc627ee6813a604bf26
BLAKE2b-256 checksum
How to use checksums
6020e9a116de28d02b7250d01bb90362cf0746637bf3eef3e231e03af5de118f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / gl_sandbox_binary-0.0.1b4-cp312-cp312-win_amd64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL gl_sandbox_binary-0.0.1b4-cp312-cp312-win_amd64.whl
Size 688.5 kB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
17602937c38db25cdddc41b83ebd841892e6a6e944c6b11e681806f8f4d8f6a5
BLAKE2b-256 checksum
How to use checksums
ff1520bddb6a39a5a7874ef0953ca62f65d0522b3e1bceaef416161023a87894
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / gl_sandbox_binary-0.0.1b4-cp312-cp312-manylinux_2_28_x86_64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while other files in this release have provenance metadata, this file does not.

We recommend further investigation before installing this file. View details.

Download URL gl_sandbox_binary-0.0.1b4-cp312-cp312-manylinux_2_28_x86_64.whl
Size 1.0 MB
Tags CPython 3.12 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
1eac08ce3bc573569536001de97b1baab01adaa9bf7a05f8de09eb27335f6272
BLAKE2b-256 checksum
How to use checksums
298b6b098948231748e1fe9796afdb84725af7cdc9213739f79a36755797d430
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"AlmaLinux","version":"8.10","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / gl_sandbox_binary-0.0.1b4-cp312-cp312-macosx_13_0_arm64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL gl_sandbox_binary-0.0.1b4-cp312-cp312-macosx_13_0_arm64.whl
Size 735.5 kB
Tags CPython 3.12 macOS 13.0+ ARM64
SHA-256 checksum
How to use checksums
fd12c12ce8709eb7907d07617f768b9f09ac97be65f16ffe6b7d26bff5ba352b
BLAKE2b-256 checksum
How to use checksums
25f1faf61fb3c15869ddd0f72fd199034dcc909b4449e442e533cc8aaa0dc953
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / gl_sandbox_binary-0.0.1b4-cp311-cp311-win_amd64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL gl_sandbox_binary-0.0.1b4-cp311-cp311-win_amd64.whl
Size 711.8 kB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
a713dd045e0595ecdb211826c54b3ba54a46a338dea08f114d9971b07ef96cfd
BLAKE2b-256 checksum
How to use checksums
ecce41dfd3dff27c56bc2303eafc6b65dae2f6f0a4cfd1ec58400b8a33c12eba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Release files / gl_sandbox_binary-0.0.1b4-cp311-cp311-manylinux_2_28_x86_64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while other files in this release have provenance metadata, this file does not.

We recommend further investigation before installing this file. View details.

Download URL gl_sandbox_binary-0.0.1b4-cp311-cp311-manylinux_2_28_x86_64.whl
Size 947.0 kB
Tags CPython 3.11 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
508e2ce6948dd764c1f66de7d1c91ccdf794e3c4bb864f2b007645f21529a1f2
BLAKE2b-256 checksum
How to use checksums
0675fd10c4d91cc08b700139a87c0c4c3983e848d43a645bdfcfff29ca25632c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"AlmaLinux","version":"8.10","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / gl_sandbox_binary-0.0.1b4-cp311-cp311-macosx_13_0_arm64.whl

Incomplete provenance

This file belongs to a release with incomplete provenance: while this file has provenance metadata, other files in this release do not.

We recommend further investigation before installing this file. View details.

Download URL gl_sandbox_binary-0.0.1b4-cp311-cp311-macosx_13_0_arm64.whl
Size 727.9 kB
Tags CPython 3.11 macOS 13.0+ ARM64
SHA-256 checksum
How to use checksums
9b0600f72096c2ea8922bbab8e0705e4d540c5735051cf661375a8c2e6ddf275
BLAKE2b-256 checksum
How to use checksums
040822aaa45f6e4a381f4390202db1672376d33d2dfe8ad38ce82b14ef66dcae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

Security for gl-sandbox-binary 0.0.1b4

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.

Incomplete provenance

3 of 9 release files were uploaded without provenance metadata.

Files with provenance 6 / 9
Files without provenance 3 / 9
Select from 9 files

Attestation for gl_sandbox_binary-0.0.1b4-cp313-cp313-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.

Transparency log

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page