# Docker (/tools/toolkits/local/docker)



**DockerTools** enable an Agent to interact with Docker containers, images, volumes, and networks.

## Prerequisites [#prerequisites]

The following example requires the `docker` and `openai` Python packages. You'll also need Docker installed and running on your system.

```shell
uv pip install agno docker openai
```

The Agent model uses an OpenAI key, separately from any toolkit provider credentials.

## Set OpenAI Key [#set-openai-key]

Set your `OPENAI_API_KEY` as an environment variable. You can get one [from OpenAI](https://platform.openai.com/account/api-keys).

<CodeBlockTabs defaultValue="Mac">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Mac">
      Mac
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Windows PowerShell">
      Windows PowerShell
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Mac">
    ```bash
    export OPENAI_API_KEY=sk-***
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Windows PowerShell">
    ```powershell
    $env:OPENAI_API_KEY = "your-openai-api-key"
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Example [#example]

The following example creates an agent that can manage Docker resources:

```python title="cookbook/91_tools/docker_tools.py"
import sys

from agno.agent import Agent

try:
    from agno.tools.docker import DockerTools

    docker_tools = DockerTools()

    docker_agent = Agent(
        name="Docker Agent",
        instructions=[
            "You are a comprehensive Docker management assistant.",
            "You can manage containers, images, volumes, and networks.",
        ],
        tools=[docker_tools],
        markdown=True,
    )

    docker_agent.print_response("List all running Docker containers", stream=True)
    docker_agent.print_response("Pull the latest nginx image", stream=True)
    docker_agent.print_response(
        "Run an nginx container named 'web-server' on port 8080", stream=True
    )

except ValueError as e:
    print(f"\n[ERROR] Docker Tool Error: {e}")
    print("\nTroubleshooting steps:")

    if sys.platform == "darwin":  # macOS
        print("1. Ensure Docker Desktop is running")
        print("2. Check Docker Desktop settings")
        print("3. Try running 'docker ps' in terminal to verify access")

    elif sys.platform == "linux":
        print("1. Check if Docker service is running:")
        print("   systemctl status docker")
        print("2. Make sure your user has permissions to access Docker:")
        print("   sudo usermod -aG docker $USER")

    elif sys.platform == "win32":
        print("1. Ensure Docker Desktop is running")
        print("2. Check Docker Desktop settings")
```

<Warning>
  `DockerTools` registers all functions by default, including `remove_container`, `remove_image`, `remove_volume`, `remove_network`, and `exec_in_container`, which runs an arbitrary command inside a container. No function filter or confirmation requirement is applied by default. Use `include_tools`/`exclude_tools` to select functions and `requires_confirmation_tools` to gate calls through [HITL](/hitl/overview).
</Warning>

For example, expose only container listing and command execution, with execution requiring confirmation:

```python
DockerTools(
    include_tools=["list_containers", "exec_in_container"],
    requires_confirmation_tools=["exec_in_container"],
)
```

## Toolkit Params [#toolkit-params]

DockerTools registers all functions below by default. Limit them with the base toolkit params:

| Parameter       | Type                  | Default | Description                        |
| --------------- | --------------------- | ------- | ---------------------------------- |
| `include_tools` | `Optional[list[str]]` | `None`  | Register only these function names |
| `exclude_tools` | `Optional[list[str]]` | `None`  | Skip these function names          |

## Toolkit Functions [#toolkit-functions]

### Container Management [#container-management]

| Function             | Description                                     |
| -------------------- | ----------------------------------------------- |
| `list_containers`    | Lists all containers or only running containers |
| `start_container`    | Starts a stopped container                      |
| `stop_container`     | Stops a running container                       |
| `remove_container`   | Removes a container                             |
| `get_container_logs` | Retrieves logs from a container                 |
| `inspect_container`  | Gets detailed information about a container     |
| `run_container`      | Creates and starts a new container              |
| `exec_in_container`  | Executes a command inside a running container   |

### Image Management [#image-management]

| Function        | Description                              |
| --------------- | ---------------------------------------- |
| `list_images`   | Lists all images on the system           |
| `pull_image`    | Pulls an image from a registry           |
| `remove_image`  | Removes an image                         |
| `build_image`   | Builds an image from a Dockerfile        |
| `tag_image`     | Tags an image                            |
| `inspect_image` | Gets detailed information about an image |

### Volume Management [#volume-management]

| Function         | Description                              |
| ---------------- | ---------------------------------------- |
| `list_volumes`   | Lists all volumes                        |
| `create_volume`  | Creates a new volume                     |
| `remove_volume`  | Removes a volume                         |
| `inspect_volume` | Gets detailed information about a volume |

### Network Management [#network-management]

| Function                            | Description                               |
| ----------------------------------- | ----------------------------------------- |
| `list_networks`                     | Lists all networks                        |
| `create_network`                    | Creates a new network                     |
| `remove_network`                    | Removes a network                         |
| `inspect_network`                   | Gets detailed information about a network |
| `connect_container_to_network`      | Connects a container to a network         |
| `disconnect_container_from_network` | Disconnects a container from a network    |

## Developer Resources [#developer-resources]

* [Tools](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/docker.py)