DockerSandbox — manages a single long-running Docker container: lifecycle (start/stop), file writes via the tar archive API, and command execution with timeout enforcement. Volumes, ports, environment variables, and capabilities are all caller-supplied.
LangChain tools — a ready-to-use set of tools that expose the sandbox to an agent: bash, read_file, write_file, edit_file, list_dir, delete_file, move_file, copy_file, make_dir, search_files, grep.

Requirements

Python ≥ 3.11
Docker daemon running locally
A Docker image to run (either pre-built or built via build_image_if_missing)

Installation

pip install docker-agent-sandbox

Or with uv, pointing at a local checkout:

# pyproject.toml
[tool.uv.sources]
docker-agent-sandbox = { path = "../docker-agent-sandbox" }

Usage

1. Create and start a sandbox

from docker_agent_sandbox import DockerSandbox

sandbox = DockerSandbox(
    container_name="my-agent-run",
    image="my-agent-image",
    dockerfile_dir="/path/to/dockerfile",  # only needed if building the image
    volumes={"/host/sandbox": {"bind": "/workspace", "mode": "rw"}},
    ports={"8080/tcp": None},              # Docker assigns a random host port
    environment={"MY_VAR": "value"},
    working_dir="/workspace",
    cap_drop=["ALL"],
    cap_add=["SYS_PTRACE"],
    security_opt=["no-new-privileges"],
)

sandbox.build_image_if_missing()
sandbox.start()

2. Inspect mapped ports

host_port = sandbox.get_host_port("8080/tcp")

3. Run commands and write files

exit_code, output = sandbox.exec("ls -la")
sandbox.write_file("/workspace/hello.py", "print('hello')")
exit_code, output = sandbox.exec("python /workspace/hello.py")

4. Bind tools to a LangChain agent

from docker_agent_sandbox import make_bash_tool, make_file_ops_tools

tools = make_file_ops_tools(sandbox) + [make_bash_tool(sandbox)]

# Pass `tools` to your LangChain / LangGraph agent as usual.

5. Tear down

sandbox.stop()

API reference

`DockerSandbox(container_name, image, dockerfile_dir, volumes, ports, environment, working_dir, network_mode, cap_drop, cap_add, security_opt)`

Parameter	Default	Description
`container_name`	—	Docker container name
`image`	`"docker-agent-sandbox"`	Docker image tag to run
`dockerfile_dir`	`None`	Directory containing the `Dockerfile`; required only if calling `build_image_if_missing`
`volumes`	`{}`	Volume bindings passed directly to Docker (same format as `docker-py`)
`ports`	`{}`	Port bindings passed directly to Docker, e.g. `{"8080/tcp": None}` for a random host port
`environment`	`{}`	Environment variables injected into the container
`working_dir`	`None`	Default working directory for `exec` calls (uses image `WORKDIR` if omitted)
`network_mode`	`"bridge"`	Docker network mode
`cap_drop`	`None`	Linux capabilities to drop
`cap_add`	`None`	Linux capabilities to add
`security_opt`	`None`	Docker security options

Methods

Method	Description
`build_image_if_missing()`	Builds the image from `dockerfile_dir` if not already present locally
`start()`	Removes any existing container with the same name and starts a fresh one
`stop()`	Removes the container
`get_host_port(container_port)`	Returns the host port Docker mapped to `container_port` (e.g. `"8080/tcp"`)
`exec(command, timeout=120)`	Runs a bash command; returns `(exit_code, stdout+stderr)`
`write_file(path, content)`	Writes a UTF-8 file inside the container using the tar archive API

Tools

Factory	Tool name	Description
`make_bash_tool(sandbox)`	`bash`	Execute a shell command
`make_file_ops_tools(sandbox)`	—	Returns all tools below as a list
`make_read_file_tool(sandbox)`	`read_file`	Read a file with offset/length pagination
`make_write_file_tool(sandbox)`	`write_file`	Write a file
`make_edit_file_tool(sandbox)`	`edit_file`	`str_replace`-style editing
`make_list_dir_tool(sandbox)`	`list_dir`	`ls -lA` a directory
`make_delete_file_tool(sandbox)`	`delete_file`	Delete a file or empty directory
`make_move_file_tool(sandbox)`	`move_file`	Move or rename
`make_copy_file_tool(sandbox)`	`copy_file`	Copy a file
`make_make_dir_tool(sandbox)`	`make_dir`	`mkdir -p`
`make_search_files_tool(sandbox)`	`search_files`	`find` by name glob
`make_grep_tool(sandbox)`	`grep`	Extended-regex search with optional recursion