> ## Documentation Index
> Fetch the complete documentation index at: https://pentest-tools.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker agent

> Deploy the VPN agent as a Docker container for internal network scanning

The Docker agent is a containerized VPN agent for environments already running Docker. It works on Linux, Windows, and macOS (including Apple Silicon).

<Info>
  VPN profiles require the **Internal network scanning** add-on.
</Info>

## Prerequisites

* Docker installed and running
* Outbound connectivity to vpn2.pentest-tools.com on TCP port 22
* Network access to internal targets from the Docker host

## Quick start

<Steps>
  <Step title="Create VPN profile">
    In Pentest-Tools.com, create a new VPN profile and copy the VPN UUID.
  </Step>

  <Step title="Pull and run">
    Run the following command, replacing `<VPN_UUID>` with your UUID:

    ```bash theme={null}
    docker pull pentesttoolscom/vpn_agent:latest && \
    docker run -d \
      --name pentest-agent \
      --restart unless-stopped \
      --cap-add=NET_ADMIN \
      --device /dev/net/tun \
      pentesttoolscom/vpn_agent:latest <VPN_UUID>
    ```

    You can also copy this command directly from the deployment menu in **Settings > VPN Profiles**.
  </Step>

  <Step title="Verify connection">
    Go to **Settings > VPN Profiles** and check that your profile shows as **Online**.
  </Step>
</Steps>

## Required capabilities

The agent needs these Linux capabilities:

| Capability     | Purpose                       |
| -------------- | ----------------------------- |
| `NET_ADMIN`    | VPN tunnel management         |
| `/dev/net/tun` | TUN device for the VPN tunnel |

## Network modes

By default, the container uses Docker's bridge network. Depending on your setup, you may need a different mode.

### Host network mode

Gives the container direct access to the host's network interfaces:

```bash theme={null}
docker run -d \
  --name pentest-agent \
  --network host \
  --cap-add=NET_ADMIN \
  --device /dev/net/tun \
  pentesttoolscom/vpn_agent:latest <VPN_UUID>
```

<Warning>
  Host network mode exposes the container's ports directly on the host machine. This can cause conflicts if ports 80, 443, or 1194 are already in use on the host. It also means the agent's network traffic is not isolated from the host.
</Warning>

### Custom Docker network

To scan containers in a specific Docker network:

```bash theme={null}
docker run -d \
  --name pentest-agent \
  --network your-internal-network \
  --cap-add=NET_ADMIN \
  --device /dev/net/tun \
  pentesttoolscom/vpn_agent:latest <VPN_UUID>
```

## Docker Compose

Set your VPN UUID as the `command` in the Compose file:

```yaml theme={null}
services:
  vpn-agent:
    image: pentesttoolscom/vpn_agent:latest
    container_name: pentest-agent
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    network_mode: host
    command: "<VPN_UUID>"
```

<Note>
  Replace `<VPN_UUID>` with the UUID from your VPN profile.
</Note>

Start the agent in the background:

```bash theme={null}
docker compose up -d
```

## Managing the agent

```bash theme={null}
# View logs
docker logs pentest-agent

# Check status
docker ps | grep pentest-agent

# Restart
docker restart pentest-agent

# Stop
docker stop pentest-agent

# Remove
docker rm -f pentest-agent
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Container exits immediately">
    * Check that the VPN UUID is provided as an argument after the image name
    * Verify `--cap-add=NET_ADMIN` is set
    * Check that the `/dev/net/tun` device is mounted
    * Check container logs: `docker logs pentest-agent`
  </Accordion>

  <Accordion title="Cannot reach internal targets">
    * Verify the container's network mode allows access to targets
    * Check host firewall rules
    * Try `--network host` mode
  </Accordion>
</AccordionGroup>

## Related topics

* [VPN profiles overview](/capabilities/vpn/overview)
* [Cloud deployment](/capabilities/vpn/cloud)
* [Troubleshooting](/capabilities/vpn/troubleshooting)