Metadata-Version: 2.4
Name: deepagents-docker-sandbox
Version: 0.0.1
Summary: Docker sandbox integration for Deep Agents
Project-URL: Homepage, https://github.com/Alex2Yang97/deepagents_docker_sandbox
Project-URL: Repository, https://github.com/Alex2Yang97/deepagents_docker_sandbox
Project-URL: Documentation, https://github.com/Alex2Yang97/deepagents_docker_sandbox#readme
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.0
Requires-Dist: docker
Description-Content-Type: text/markdown

# deepagents-docker-sandbox

Docker sandbox integration for [Deep Agents](https://github.com/langchain-ai/deepagents).

This package exposes `DockerSandbox` as the Deep Agents-compatible backend and `DockerSandboxRuntime` as the lower-level Docker runtime.

## Quick install (PyPI)

When/if the project is published to PyPI end users should be able to install with:

```bash
pip install deepagents-docker-sandbox
```

## Local development

The project installs `deepagents` from PyPI by default, so a standalone checkout can run with `uv sync --group test` or the test commands below.

## Usage with DockerSandbox

```python
from deepagents_docker_sandbox import DockerSandbox

with DockerSandbox.create(default_timeout=120) as sandbox:
    result = sandbox.execute("echo hello")
    print(result.output)
```

## Low-level DockerSandboxRuntime example

For direct access to the lower-level Docker runtime:

```python
from deepagents_docker_sandbox import DockerSandboxRuntime

with DockerSandboxRuntime.create() as runtime:
    runtime.write_file("/tmp/hello.txt", "hello")
    result = runtime.run("cat /tmp/hello.txt")
    print(result.stdout)
```

## Requirements

This package requires a working Docker daemon for real sandbox execution.

The default runtime creates a container from `python:3.11-slim`, injects a small helper process, exposes that helper on a random host port, and applies conservative resource and security settings.

## Security

Docker isolation depends on the host Docker daemon and container configuration. Do not treat this package as a complete multi-tenant security boundary without additional host hardening, image controls, network controls, and workload isolation.

## Tests

Default suite:

```bash
PYTHONPATH=src uv run --group test pytest -q
```

Docker-gated runtime round trip:

```bash
DEEPAGENTS_DOCKER_SANDBOX_TESTS=1 PYTHONPATH=src uv run --group test pytest tests/test_docker_runtime.py::test_optional_docker_runtime_roundtrip -q
```

Deep Agents standard sandbox integration checks:

```bash
DEEPAGENTS_DOCKER_SANDBOX_RUN_INTEGRATION=1 PYTHONPATH=src uv run --group test pytest tests/integration_tests -q
```

## Notebooks

Example notebooks live in `notebooks/` and are not part of the installed library.

## Release process

Releases are published through GitHub Actions with PyPI Trusted Publishing.

### One-time publishing setup

Configure pending trusted publishers on TestPyPI and PyPI for the `deepagents-docker-sandbox` project:

- Owner: `Alex2Yang97`
- Repository: `deepagents_docker_sandbox`
- Workflow: `publish.yml`
- TestPyPI environment: `testpypi`
- PyPI environment: `pypi`

In GitHub repository settings, create matching Actions environments:

- `testpypi`: allow manual deployments from `main`.
- `pypi`: require reviewer approval and restrict deployments to release tags matching `v*` when available.

Protect `main` with pull request reviews, required CI status checks, resolved conversations, and disabled force pushes/deletions before publishing production releases.

### Publishing a release

1. Open a pull request and wait for the CI workflow to pass.
2. Run the `Publish` workflow manually from `main` to publish the current version to TestPyPI.
3. Smoke test the TestPyPI package in a clean environment:

```bash
python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ deepagents-docker-sandbox==0.0.1
python -c "from deepagents_docker_sandbox import DockerSandboxRuntime; print(DockerSandboxRuntime)"
```

4. Create and push a version tag, for example `v0.0.1`, to publish the same version to PyPI.

Before tagging a release, keep the version in `pyproject.toml` and `src/deepagents_docker_sandbox/_version.py` synchronized.
