smolagents-groundbox
Run smolagents' CodeAgent code in a
Groundbox sandbox: a Linux microVM (Firecracker) per agent, started in
about a second.
GroundboxExecutor is a remote Python executor, built like smolagents' own E2B, Modal, Docker and
Blaxel executors. Pass it to CodeAgent(executor=...).
Needs smolagents 1.25.0 or newer. executor= arrived in 1.23.0, but 1.25.0 moved remote
executors from pickle to safe JSON serialization (allow_pickle), and this package uses that.
Install
pip install smolagents-groundbox
Set GROUNDBOX_API_KEY (create one at https://app.groundbox.dev/keys), or pass api_key=.
Use
from smolagents import CodeAgent, InferenceClientModel
from smolagents_groundbox import GroundboxExecutor
with CodeAgent(
tools=[],
model=InferenceClientModel(),
executor=GroundboxExecutor(additional_imports=["numpy"]),
) as agent:
agent.run("Compute the 20th Fibonacci number with numpy.")
# Leaving the block deletes the sandbox.
Without the with block, call agent.cleanup() (or executor.cleanup()) when you are done. A
sandbox the executor created also ends on its own after timeout_minutes (60 unless you set it).
Options
GroundboxExecutor(
additional_imports=["pandas"], # pip installed in the sandbox before the first step
create_kwargs={ # passed to Groundbox.create_sandbox
"cpus": 2,
"memory_gb": 4,
"image": "python:3.12-slim", # any public Docker image, or a template=...
"allow_hosts": ["pypi.org", "files.pythonhosted.org"],
"timeout_minutes": 30,
},
timeout_seconds=300, # longest one code action may run (default 300)
sandbox_id=None, # reuse a running sandbox; it is not deleted on cleanup
allow_pickle=False, # same meaning as in smolagents' built-in executors
)
logger is optional: CodeAgent does not hand its logger to an executor you build yourself, so
by default the executor logs to a new AgentLogger. Pass logger=agent.logger to share one.
How it works
The executor starts the sandbox, uploads a small kernel (standard library only), and starts it as
a background command. Each code action is sent to that one Python process, so variables, imports,
functions and tools stay from step to step, the way the built-in executors keep them in a Jupyter
kernel. Tools and final_answer go through smolagents' own send_tools, send_variables and
final-answer handling.
- Output: the value of the last expression, as its
repr(a PIL image comes back as an image), like the text result of the Jupyter-based executors. - Logs: everything printed to stdout and stderr during the step, including subprocesses.
- Errors: raised as
AgentErrorwith the exception name, message and traceback. - Timeouts: past
timeout_seconds, the step is interrupted withExecutionTimeout; the namespace is kept. - A step that kills the Python process (
os._exit, running out of memory) restarts the kernel and says so; earlier variables are gone.
The default image is Ubuntu with Python 3.12, running as the user runner (with sudo); packages
are installed with pip --user. With image=, commands run as root.
When the agent starts, smolagents pip installs each tool's requirements in the sandbox. Its own
final_answer tool asks for numpy and pillow, so the first run in a fresh sandbox spends a few
seconds installing them (the same happens with the built-in executors). To skip that, start from a
template that has them: create_kwargs={"template": "..."}.
Limits
- No Jupyter: IPython syntax such as
!pip installor%magiclines is not supported in agent code (the built-in executors run on Jupyter and accept it). Usesubprocessoradditional_importsinstead. - Rich outputs other than PIL images (HTML, charts) come back as their
repr. - One code action at a time per executor; each step makes one API call (about 0.2 s overhead).
- Not built into smolagents: use
executor=GroundboxExecutor(), notexecutor_type="groundbox".
Tests
pip install -e '.[test]'
pytest # unit tests, with a local stand-in for the sandbox
GROUNDBOX_API_KEY=gbx_... pytest tests/test_live.py # against Groundbox itself
License
MIT. See LICENSE.
Metadata
Release files for smolagents-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 |
|---|---|---|---|---|
| smolagents_groundbox-0.1.0.tar.gz | 13.6 kB | Without provenance | Details for smolagents_groundbox-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| smolagents_groundbox-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for smolagents_groundbox-0.1.0-py3-none-any.whl |
Total release size: 25.4 kB
Release files / smolagents_groundbox-0.1.0.tar.gz
| Download URL | smolagents_groundbox-0.1.0.tar.gz |
|---|---|
| Size | 13.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
57d23f8e4a3669a9db08218f3c45abdf4bc5fae417f20fda41b3d0a76974e582
|
|
BLAKE2b-256 checksum How to use checksums |
9700007085943d1aa8bece204438424f1e5fcaa0bbdc6ba3cb728bfcf1593e8e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Release files / smolagents_groundbox-0.1.0-py3-none-any.whl
| Download URL | smolagents_groundbox-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
55174612e31c1ccd64254ec1b71b142d5f6b64c49abdb1e067c7fce536864c61
|
|
BLAKE2b-256 checksum How to use checksums |
3ed38ef0b6e6bbc00463207d04de19b9e3b7883824e9a876a3bad37e4150ad0f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Security for smolagents-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.