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_filescan read a file therunneruser cannot (for example one with mode000), where other sandboxes answerpermission_denied. Files it writes belong torunner. - 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 (
truncatedis alwaysFalse); a background command keeps its last 32 MB of output. --sandbox-snapshot-namedoes 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.GroundboxSandboxalone 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.