docker-agent-sandbox

A Docker-based sandbox and LangChain tool set for LLM agents that need a safe, isolated shell environment.

What it provides

• DockerSandbox — manages a single long-running Docker container: lifecycle (start/stop), file writes via the tar archive API, and command execution with timeout enforcement.
• 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.

The sandbox directory is bind-mounted inside the container, so the agent works with stable paths regardless of where the sandbox lives on the host.

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(
    sandbox_dir="/tmp/my-sandbox",   # bind-mounted into the container
    container_name="my-agent-run",
    container_workdir="/workspace",  # path inside the container
    image="my-agent-image",
    dockerfile_dir="/path/to/dockerfile",  # only needed if building the image
)

sandbox.build_image_if_missing()
sandbox.start()

2. 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")

3. 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.

4. Tear down

sandbox.stop()

API reference

DockerSandbox(sandbox_dir, container_name, container_workdir, pin_mcp_port, image, dockerfile_dir)

Parameter	Default	Description
sandbox_dir	—	Host directory bind-mounted into the container
container_name	—	Docker container name
container_workdir	"/workspace"	Working directory inside the container
pin_mcp_port	8080	Port exposed by a sidecar MCP server (if any)
image	"docker-agent-sandbox"	Docker image tag to run
dockerfile_dir	None	Directory containing the Dockerfile; required only if calling build_image_if_missing

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, starts a fresh one, and waits for the MCP port
stop()	Removes the container
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

Security notes

Containers are started with cap_drop=ALL, cap_add=SYS_PTRACE (needed for debuggers/tracers), and no-new-privileges. Network mode is bridge with no explicit outbound rules — restrict further via Docker network policies if needed.