langchain-upstash-box

Upstash Box sandbox integration for Deep Agents.

An Upstash Box is a secure, isolated cloud container with a full Linux shell, filesystem, git, and a runtime. This package wraps a box as a Deep Agents SandboxBackendProtocol, so agents can run shell commands and read/write files inside it.

Quick install

uv add langchain-upstash-box
# or: pip install langchain-upstash-box

Usage

Set your Box API key (create one in the Upstash Console):

export UPSTASH_BOX_API_KEY="box_xxxxxxxxxxxx"

Provision a box and use it as a sandbox backend:

from langchain_upstash_box import UpstashBoxSandbox

# Creates a box and waits until it is ready.
sandbox = UpstashBoxSandbox.create(runtime="python")

result = sandbox.execute("echo hello")
print(result.output)      # "hello"
print(result.exit_code)   # 0

# Filesystem helpers (ls / read / write / edit / glob / grep) are provided by
# BaseSandbox on top of execute() + upload/download.
sandbox.write("/workspace/home/hello.py", "print('hi from box')")
print(sandbox.read("/workspace/home/hello.py").content)

sandbox.delete()

Wrap an existing box instead of creating one:

from langchain_upstash_box import UpstashBoxSandbox

sandbox = UpstashBoxSandbox(box_id="current-wasp-05510")

Use with a Deep Agent

from deepagents import create_deep_agent
from langchain_upstash_box import UpstashBoxSandbox

sandbox = UpstashBoxSandbox.create(runtime="python")

agent = create_deep_agent(
    model="anthropic:claude-opus-4-6",
    backend=sandbox,
)

agent.invoke({"messages": [{"role": "user", "content": "Create app.py and run it."}]})

🤔 What is this?

UpstashBoxSandbox subclasses BaseSandbox and implements execute(), upload_files(), download_files(), and id. All other filesystem tool operations are derived from those by BaseSandbox, which relies on python3 being available inside the box (it is, on the default Debian-based runtimes).

Configuration

Setting	Source
API key	api_key= argument or UPSTASH_BOX_API_KEY env var
Base URL	base_url= argument or UPSTASH_BOX_BASE_URL env var (defaults to https://us-east-1.box.upstash.com)

Development

make test              # unit tests (no credentials needed)
make integration_test  # integration tests (requires UPSTASH_BOX_API_KEY)
make lint
make format

💁 Contributing

Issues and pull requests are welcome at https://github.com/upstash/box.

License

MIT