Skip to main content

langchain-groundbox

Groundbox sandboxes for Deep Agents: a sandbox backend for deepagents, and a sandbox provider for Deep Agents Code (dcode).

Each sandbox is a Firecracker microVM running Ubuntu 24.04 on dedicated cores, as the user runner (with sudo), with python3, bash and git installed.

Install

With Deep Agents Code:

dcode install langchain-groundbox --package

With plain deepagents (or to test against an editable dcode):

pip install langchain-groundbox

Set your API key (create one at https://app.groundbox.dev/keys):

export GROUNDBOX_API_KEY=gbx_...

Use it in dcode

dcode --sandbox groundbox

The provider registers itself under the deepagents_code.sandbox_providers entry point as groundbox. dcode starts a sandbox, runs the agent's commands and file edits in it, and deletes it when the session ends.

dcode --sandbox groundbox --sandbox-setup ./setup.sh           # run a script in the sandbox first
dcode --sandbox groundbox --sandbox-id sbx_...                   # attach to a sandbox you started; it is not deleted
dcode --sandbox groundbox --sandbox-snapshot-name my-template    # start from a Groundbox template
dcode --sandbox groundbox --sandbox-snapshot-name snap_...       # start from a kept snapshot

To make it the default, in ~/.deepagents/config.toml:

[sandboxes]
default = "groundbox"

Settings

Each is read from the environment, also with a DEEPAGENTS_CODE_ prefix (which wins):

Variable What it does Default
GROUNDBOX_API_KEY API key (required)
GROUNDBOX_API_URL API base https://api.groundbox.dev/v1
GROUNDBOX_TEMPLATE Template (id, name or name:version) for new sandboxes your team's default template, else Groundbox's image
GROUNDBOX_IMAGE Docker image for new sandboxes, e.g. python:3.12-slim (commands run as root, in /root)
GROUNDBOX_CPUS vCPUs, 1 to 16 2
GROUNDBOX_MEMORY_GB Memory in GB 2 per vCPU
GROUNDBOX_DISK_GB Minimum disk in GB 20
GROUNDBOX_SANDBOX_TIMEOUT_MINUTES Sandbox lifetime 60
GROUNDBOX_WORKDIR Folder the agent works in /home/runner (/root with an image)

The same settings, and a few more (env, metadata, allow_hosts, deny_hosts, secrets, idle_timeout_seconds, command_timeout), are keyword arguments of GroundboxProvider.get_or_create(). To pass them from dcode's config, declare the provider there with its class path:

[sandboxes.providers.groundbox]
class_path = "langchain_groundbox.provider:GroundboxProvider"
working_dir = "/home/runner"
supports_snapshot_name = true

[sandboxes.providers.groundbox.params]
cpus = 4
timeout_minutes = 180
allow_hosts = ["github.com", "*.githubusercontent.com", "pypi.org", "files.pythonhosted.org"]

Use it with deepagents

from deepagents import create_deep_agent
from groundbox import Groundbox
from langchain_groundbox import GroundboxSandbox

gb = Groundbox()  # reads GROUNDBOX_API_KEY
sandbox = gb.create_sandbox(cpus=2, timeout_minutes=60)
try:
    backend = GroundboxSandbox(client=gb, sandbox_id=sandbox["id"])
    agent = create_deep_agent(
        model="anthropic:claude-sonnet-4-5",
        backend=backend,
        system_prompt="You work in a Linux sandbox. Your home is /home/runner.",
    )
    agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": "Write and run a Python script that prints the first 10 primes.",
                }
            ]
        }
    )
finally:
    gb.delete_sandbox(sandbox["id"])

GroundboxSandbox(client, sandbox_id, workdir="/home/runner", timeout=1800, env=None): timeout is the default per-command timeout in seconds (0 for none).

How it maps

Deep Agents Groundbox
execute(command, timeout=) POST /exec with bash -c (or sh -c when the image has no bash), in workdir. Over 60 minutes, or timeout=0: a background command whose output is read until it ends
upload_files / download_files the file API (PUT / GET /files); parent folders are made
read, write, edit, ls, glob, grep Deep Agents' own BaseSandbox helpers over execute() (they need python3)
get_or_create(sandbox_id=...) GET /sandboxes/{id}; a paused sandbox is resumed, a shut-down one started
get_or_create(snapshot=...) snap_... starts from a kept snapshot, anything else names a template
delete DELETE /sandboxes/{id}

Limits

  • The free trial allows 2 sandboxes at a time, 2 vCPU, 4 GB and 60 minutes each. Kept snapshots, templates and stop/start need the paid plan.
  • The file API acts as root, so download_files can read a file the runner user cannot (for example one with mode 000), where other sandboxes answer permission_denied. Files it writes belong to runner.
  • Commands and files are synchronous calls; the async methods (aexecute, aget_or_create, ...) run them in a thread, as Deep Agents' defaults do.
  • Output is not cut by the backend (truncated is always False); a background command keeps its last 32 MB of output.
  • --sandbox-snapshot-name does not build a missing template: make it first (https://groundbox.dev/docs/templates).
  • A call the API refuses for now (rate_limited, no_capacity) is tried up to four more times, waiting as long as the API asks (at most 30 seconds each); other errors come back as the command's output (exit code 1) or as a file error.
  • The provider module imports deepagents_code, which needs Python 3.14. GroundboxSandbox alone works on Python 3.11+.

Development

pip install -e . pytest pytest-asyncio langchain-tests deepagents-code   # deepagents-code: Python 3.14
pytest tests/unit_tests
GROUNDBOX_API_KEY=gbx_... pytest tests/integration_tests   # creates and deletes real sandboxes

The live tests run LangChain's standard SandboxIntegrationTests suite. Seven of its tests are marked expected-to-fail: langchain-tests 1.1.9 still expects relative glob() paths and a write() that refuses existing files, which deepagents 0.7's BaseSandbox changed.

MIT licensed; see LICENSE.

Metadata

Release files for langchain-groundbox 0.1.0

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

Source distribution (sdist)

Source distribution for langchain-groundbox 0.1.0
File Size Uploaded Provenance Actions
langchain_groundbox-0.1.0.tar.gz 17.5 kB Without provenance Details for langchain_groundbox-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for langchain-groundbox 0.1.0
File Interpreter ABI Platform Actions
langchain_groundbox-0.1.0-py3-none-any.whl Python 3 none any Details for langchain_groundbox-0.1.0-py3-none-any.whl

Total release size: 31.2 kB

Release files / langchain_groundbox-0.1.0.tar.gz

Download URL langchain_groundbox-0.1.0.tar.gz
Size 17.5 kB
Tags Source
SHA-256 checksum
How to use checksums
c3e09e0439c38f5ba953e7e9700115371235c95a1bcf4013d526d219893089df
BLAKE2b-256 checksum
How to use checksums
345e1436e76de29f8ce423e52f424c12afefe01e74bb77f939e2b88c360ebc47
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / langchain_groundbox-0.1.0-py3-none-any.whl

Download URL langchain_groundbox-0.1.0-py3-none-any.whl
Size 13.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
47835b359bcd6502bdc3c30365e1e21a1372703e03b6b817adbb183051088b66
BLAKE2b-256 checksum
How to use checksums
0e934ffa297f161dcab6cfbd9f8fbc36fb4034aa5ac31c4bbdae8a63cee4a9b0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for langchain-groundbox 0.1.0

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

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