Metadata-Version: 2.5
Name: langchain-pandastack
Version: 0.1.0
Summary: PandaStack sandbox integration for Deep Agents
Project-URL: Homepage, https://pandastack.ai
Project-URL: Repository, https://github.com/pandastack-io/pandastack-ai
Project-URL: Documentation, https://docs.pandastack.ai
Project-URL: Issues, https://github.com/pandastack-io/pandastack-ai/issues
Author: PandaStack
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,deepagents,firecracker,langchain,pandastack,sandbox
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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.8.0,>=0.6.0
Requires-Dist: pandastack<1.0.0,>=0.10.0
Description-Content-Type: text/markdown

# langchain-pandastack

Run [Deep Agents](https://docs.langchain.com/oss/python/deepagents/overview) in
[PandaStack](https://pandastack.ai) sandboxes. Each sandbox is its own
Firecracker microVM, so the code an agent writes runs away from your machine.

This package gives you two things:

- `PandaStackSandbox`, a sandbox backend for the Deep Agents SDK.
- a `pandastack` sandbox provider for Deep Agents Code (`dcode --sandbox pandastack`).

## Install

```bash
pip install langchain-pandastack
```

You need a PandaStack API key. Create one in the
[dashboard](https://app.pandastack.ai) and export it:

```bash
export PANDASTACK_API_KEY=pds_...
```

## Deep Agents SDK

Create a sandbox with the PandaStack SDK and wrap it:

```python
from deepagents import create_deep_agent
from langchain_anthropic import ChatAnthropic
from langchain_pandastack import PandaStackSandbox
from pandastack import Sandbox

sandbox = Sandbox.create(template="base", ttl_seconds=30 * 60)
backend = PandaStackSandbox(sandbox=sandbox)

agent = create_deep_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    system_prompt="You are a Python coding assistant with sandbox access.",
    backend=backend,
)

try:
    result = agent.invoke(
        {"messages": [{"role": "user", "content": "Write and run a hello world script."}]}
    )
    print(result["messages"][-1].content)
finally:
    sandbox.kill()
```

You can also call the backend directly:

```python
result = backend.execute("python3 --version")
print(result.output, result.exit_code)
```

`PandaStackSandbox` does not create or delete sandboxes. You do that with the
PandaStack SDK, so you keep control of templates, snapshots and forks.

## Deep Agents Code

Install the package into the `dcode` environment, then pick the provider:

```bash
dcode --install langchain-pandastack --package
export PANDASTACK_API_KEY=pds_...
dcode --sandbox pandastack
```

`dcode` creates a sandbox when the session starts and deletes it when the
session ends. To attach to a sandbox you already have:

```bash
dcode --sandbox pandastack --sandbox-id <sandbox-id>
```

### Settings

| Variable | Default | Meaning |
| --- | --- | --- |
| `PANDASTACK_API_KEY` | (required) | Your API key. Without it, the key saved by `pandastack login` is used. |
| `PANDASTACK_API` | PandaStack cloud | API address, for a self-hosted PandaStack. |
| `PANDASTACK_TEMPLATE` | `base` | Template for new sandboxes. |
| `PANDASTACK_SANDBOX_TTL` | `1800` | Seconds of idle time after which PandaStack stops the sandbox. |

Each variable can also be set with a `DEEPAGENTS_CODE_` prefix
(`DEEPAGENTS_CODE_PANDASTACK_API_KEY`). The prefixed one wins.

## Things to know

- **Working directory.** Commands run in `/workspace`. Pass `workdir=` to
  change it.
- **One output.** A command's stdout and stderr come back together, in the
  order the command wrote them.
- **Timeouts.** A command gets 30 minutes by default. Pass `timeout=` to
  `execute()`, or `timeout=0` for no limit. A command that hits its limit is
  stopped inside the sandbox and returns exit code 124 with the output it had
  produced.
- **Background processes.** A command can start a server with `&` and return.
  The process keeps running in the sandbox and does not keep the call open.
- **Lost connection.** If the connection to the sandbox drops before a command
  reports an exit code, `execute()` returns `exit_code=None`. The command may
  have finished or not, so check before running it again.
- **Idle sandboxes stop.** PandaStack stops a sandbox after its idle time
  (`ttl_seconds`). The Deep Agents Code provider sets 30 minutes.
- **Template needs.** The sandbox needs `base64` and `mktemp` for every
  command, `timeout` for time limits, and `python3` for the file tools (read,
  edit, grep, glob). PandaStack's own templates have all of them. In a custom
  template without `timeout`, commands run with no limit.

## Development

```bash
uv sync --group test
make test
make lint
```

Integration tests create real sandboxes and need a key:

```bash
PANDASTACK_API_KEY=pds_... make integration_test
```

## License

Apache-2.0
