Metadata-Version: 2.4
Name: langchain-upstash-box
Version: 0.0.2
Summary: Upstash Box sandbox integration for Deep Agents
Project-URL: Homepage, https://github.com/upstash/langchain-upstash-box
Project-URL: Repository, https://github.com/upstash/langchain-upstash-box
Project-URL: Documentation, https://upstash.com/docs/box
License: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <4.0,>=3.11
Requires-Dist: deepagents<0.7.0,>=0.6.8
Requires-Dist: httpx>=0.27.0
Description-Content-Type: text/markdown

# langchain-upstash-box

[Upstash Box](https://upstash.com/docs/box) sandbox integration for [Deep Agents](https://docs.langchain.com/oss/python/deepagents/overview).

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`](https://reference.langchain.com/python/deepagents/backends/protocol/SandboxBackendProtocol), so agents can run shell commands and read/write files inside it.

## Quick install

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

## Usage

Set your Box API key (create one in the [Upstash Console](https://console.upstash.com)):

```bash
export UPSTASH_BOX_API_KEY="box_xxxxxxxxxxxx"
```

Provision a box and use it as a sandbox backend:

```python
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:

```python
from langchain_upstash_box import UpstashBoxSandbox

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

### Use with a Deep Agent

```python
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`](https://reference.langchain.com/python/deepagents/backends/sandbox/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

```bash
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
