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.1b3

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.1b3
File Actions
gl_sandbox_binary-0.0.1b3-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details for gl_sandbox_binary-0.0.1b3-cp313-cp313-win_amd64.whl
gl_sandbox_binary-0.0.1b3-cp313-cp313-manylinux_2_31_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.31+ x86-64 Details for gl_sandbox_binary-0.0.1b3-cp313-cp313-manylinux_2_31_x86_64.whl
gl_sandbox_binary-0.0.1b3-cp313-cp313-macosx_13_0_arm64.whl CPython 3.13 CPython 3.13 macOS 13.0+ ARM64 Details for gl_sandbox_binary-0.0.1b3-cp313-cp313-macosx_13_0_arm64.whl
gl_sandbox_binary-0.0.1b3-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for gl_sandbox_binary-0.0.1b3-cp312-cp312-win_amd64.whl
gl_sandbox_binary-0.0.1b3-cp312-cp312-manylinux_2_31_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.31+ x86-64 Details for gl_sandbox_binary-0.0.1b3-cp312-cp312-manylinux_2_31_x86_64.whl
gl_sandbox_binary-0.0.1b3-cp312-cp312-macosx_13_0_arm64.whl CPython 3.12 CPython 3.12 macOS 13.0+ ARM64 Details for gl_sandbox_binary-0.0.1b3-cp312-cp312-macosx_13_0_arm64.whl
gl_sandbox_binary-0.0.1b3-cp311-cp311-win_amd64.whl CPython 3.11 CPython 3.11 Windows x86-64 Details for gl_sandbox_binary-0.0.1b3-cp311-cp311-win_amd64.whl
gl_sandbox_binary-0.0.1b3-cp311-cp311-manylinux_2_31_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.31+ x86-64 Details for gl_sandbox_binary-0.0.1b3-cp311-cp311-manylinux_2_31_x86_64.whl
gl_sandbox_binary-0.0.1b3-cp311-cp311-macosx_13_0_arm64.whl CPython 3.11 CPython 3.11 macOS 13.0+ ARM64 Details for gl_sandbox_binary-0.0.1b3-cp311-cp311-macosx_13_0_arm64.whl

Total release size: 7.4 MB

Release files / gl_sandbox_binary-0.0.1b3-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.1b3-cp313-cp313-win_amd64.whl
Size 688.8 kB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
4fe9c98af86719d8ffe724a1e9bb7f11e9fd618f001e328354ab8695bcecd816
BLAKE2b-256 checksum
How to use checksums
ce305b6f1b74cd5a9ab59a32ac9427792f606e4eab1a59ebeb1d3d27a6d2fe4b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 8, 2026.

Transparency log

Release files / gl_sandbox_binary-0.0.1b3-cp313-cp313-manylinux_2_31_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.1b3-cp313-cp313-manylinux_2_31_x86_64.whl
Size 1.1 MB
Tags CPython 3.13 Linux glibc 2.31+ x86-64
SHA-256 checksum
How to use checksums
95ec095cfbc6e1f43b74f54843160b1d57a9a8d078e1ad156182502b278225c8
BLAKE2b-256 checksum
How to use checksums
8c21b7fb923c7667552adb504c38f35dd304047ae9e2b12869013d70a737df75
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.8.24

Release files / gl_sandbox_binary-0.0.1b3-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.1b3-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
a53051703193dd6430cd6b8e0ae7914bc34f20971b7f3795d5c91b1d9782818a
BLAKE2b-256 checksum
How to use checksums
bea3e8c4fa4859790a40902af1f02714a6c14ad7bb30b2129517e3de362f8f35
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 8, 2026.

Transparency log

Release files / gl_sandbox_binary-0.0.1b3-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.1b3-cp312-cp312-win_amd64.whl
Size 688.6 kB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
efd01eadc74b15f3abb3774aedff28f5f4d600d11b06ef076901af742bd6dd12
BLAKE2b-256 checksum
How to use checksums
d88b40d90a5b51ae62a9fc64104bce5beebd870f78e5eb54d88d63ffb37e55eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 8, 2026.

Transparency log

Release files / gl_sandbox_binary-0.0.1b3-cp312-cp312-manylinux_2_31_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.1b3-cp312-cp312-manylinux_2_31_x86_64.whl
Size 1.1 MB
Tags CPython 3.12 Linux glibc 2.31+ x86-64
SHA-256 checksum
How to use checksums
e050f034071147c5db9fb6efc7401d66b0de078a91eea39d8e5f9cb757ec2933
BLAKE2b-256 checksum
How to use checksums
18188c99305af57e0f9c407b34d8df62284b36c334cdbd8e5b02fd9462c15001
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.8.24

Release files / gl_sandbox_binary-0.0.1b3-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.1b3-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
ad1e9b80df280cc230c2a0b740e9c808d4bce1abe597525d238e436b41a56a21
BLAKE2b-256 checksum
How to use checksums
fd85ca83ead9c0950592cbb6645c90f9ad191deb614d49c7cd8c7a6fcaefef05
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 8, 2026.

Transparency log

Release files / gl_sandbox_binary-0.0.1b3-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.1b3-cp311-cp311-win_amd64.whl
Size 711.8 kB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
96cdddf1df9ea4eebe2cf73b77a4d2d026222773a79f9ba02c91dd979b60f82c
BLAKE2b-256 checksum
How to use checksums
5c833485edf9704583e4718333dc7ab3101be47520bfe81d4fcf12e4faec0646
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 8, 2026.

Transparency log

Release files / gl_sandbox_binary-0.0.1b3-cp311-cp311-manylinux_2_31_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.1b3-cp311-cp311-manylinux_2_31_x86_64.whl
Size 969.0 kB
Tags CPython 3.11 Linux glibc 2.31+ x86-64
SHA-256 checksum
How to use checksums
d5a0618b51fe04f0905f49a61347f5228a21ab65f62f93965231e46419d3bc66
BLAKE2b-256 checksum
How to use checksums
c5c6e331710bb0efc1c2c962ab9e9ebfbba924dbec6a5f37149fd44c8bd270f6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.8.24

Release files / gl_sandbox_binary-0.0.1b3-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.1b3-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
5f7a452ea41037e54e9c323e5985173593af8e9ea5ee251419cde899ad0cedbd
BLAKE2b-256 checksum
How to use checksums
9c39aa428a9e0104d8db5896888638e9d6d1351ad22da55197c65ab876b81605
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 8, 2026.

Transparency log

Security for gl-sandbox-binary 0.0.1b3

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.1b3-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 8, 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