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

# Create Network

> Create a new Docker network in a specific environment

## Overview

Creates a new Docker network with the specified configuration. This endpoint supports all network drivers including bridge, overlay, macvlan, and custom drivers.

## Authentication

This endpoint requires authentication via cookies. The user must have the `networks:create` permission for the specified environment.

## Query Parameters

<ParamField query="env" type="integer" required>
  The environment ID where the network will be created. Required parameter.
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
  Network name. Must be unique within the environment.
</ParamField>

<ParamField body="driver" type="string" default="bridge">
  Network driver to use. Options: `bridge`, `host`, `overlay`, `macvlan`, `ipvlan`, or custom driver name.
</ParamField>

<ParamField body="internal" type="boolean" default={false}>
  Whether to restrict external access to the network. Internal networks have no connectivity to external networks.
</ParamField>

<ParamField body="attachable" type="boolean" default={false}>
  Enable manual container attachment. Useful for swarm overlay networks that need standalone container access.
</ParamField>

<ParamField body="ingress" type="boolean" default={false}>
  Create as swarm ingress network. Only one ingress network can exist per swarm.
</ParamField>

<ParamField body="enableIPv6" type="boolean" default={false}>
  Enable IPv6 networking.
</ParamField>

<ParamField body="options" type="object" default={{}}>
  Network driver options as key-value pairs.

  <Expandable title="Common Options">
    **Bridge Driver:**

    * `com.docker.network.bridge.name`: Custom bridge name
    * `com.docker.network.bridge.enable_icc`: Enable inter-container connectivity (true/false)
    * `com.docker.network.bridge.enable_ip_masquerade`: Enable IP masquerading (true/false)
    * `com.docker.network.bridge.host_binding_ipv4`: Default IP when binding ports

    **Macvlan Driver:**

    * `parent`: Parent interface (e.g., "eth0")
    * `macvlan_mode`: Mode (bridge/vepa/passthru/private)

    **Overlay Driver:**

    * `encrypted`: Enable encryption ("true"/"false")
  </Expandable>
</ParamField>

<ParamField body="labels" type="object" default={{}}>
  User-defined labels as key-value pairs for organizing and identifying networks.
</ParamField>

<ParamField body="ipam" type="object">
  IP Address Management (IPAM) configuration.

  <Expandable title="IPAM Configuration">
    <ParamField body="ipam.driver" type="string" default="default">
      IPAM driver name.
    </ParamField>

    <ParamField body="ipam.config" type="array" default={[]}>
      Array of IPAM configuration objects.

      <Expandable title="Config Object">
        <ParamField body="subnet" type="string">
          Subnet in CIDR format (e.g., "172.18.0.0/16")
        </ParamField>

        <ParamField body="gateway" type="string">
          Gateway IP address (e.g., "172.18.0.1")
        </ParamField>

        <ParamField body="ipRange" type="string">
          IP range to allocate container IPs from (e.g., "172.18.5.0/24")
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="ipam.options" type="object" default={{}}>
      IPAM driver-specific options.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the network was created successfully
</ResponseField>

<ResponseField name="id" type="string">
  The ID of the newly created network
</ResponseField>

## Error Responses

<ResponseExample>
  ```json 400 Validation Error theme={null}
  {
    "error": "Network name is required"
  }
  ```

  ```json 403 Permission Denied theme={null}
  {
    "error": "Permission denied"
  }
  ```

  ```json 403 Environment Access Denied theme={null}
  {
    "error": "Access denied to this environment"
  }
  ```

  ```json 500 Server Error theme={null}
  {
    "error": "Failed to create network",
    "details": "network with name app-network already exists"
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL - Basic theme={null}
  curl -X POST 'https://your-dockhand.com/api/networks?env=1' \
    -H 'Content-Type: application/json' \
    -H 'Cookie: session=your-session-cookie' \
    -d '{
      "name": "app-network",
      "driver": "bridge"
    }'
  ```

  ```bash cURL - With IPAM theme={null}
  curl -X POST 'https://your-dockhand.com/api/networks?env=1' \
    -H 'Content-Type: application/json' \
    -H 'Cookie: session=your-session-cookie' \
    -d '{
      "name": "app-network",
      "driver": "bridge",
      "ipam": {
        "config": [{
          "subnet": "172.18.0.0/16",
          "gateway": "172.18.0.1",
          "ipRange": "172.18.5.0/24"
        }]
      },
      "options": {
        "com.docker.network.bridge.name": "br-app",
        "com.docker.network.bridge.enable_icc": "true"
      },
      "labels": {
        "app": "myapp",
        "environment": "production"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://your-dockhand.com/api/networks?env=1', {
    method: 'POST',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'app-network',
      driver: 'bridge',
      ipam: {
        config: [{
          subnet: '172.18.0.0/16',
          gateway: '172.18.0.1',
          ipRange: '172.18.5.0/24'
        }]
      },
      options: {
        'com.docker.network.bridge.name': 'br-app',
        'com.docker.network.bridge.enable_icc': 'true'
      },
      labels: {
        app: 'myapp',
        environment: 'production'
      }
    })
  });

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://your-dockhand.com/api/networks',
      params={'env': 1},
      cookies={'session': 'your-session-cookie'},
      json={
          'name': 'app-network',
          'driver': 'bridge',
          'ipam': {
              'config': [{
                  'subnet': '172.18.0.0/16',
                  'gateway': '172.18.0.1',
                  'ipRange': '172.18.5.0/24'
              }]
          },
          'options': {
              'com.docker.network.bridge.name': 'br-app',
              'com.docker.network.bridge.enable_icc': 'true'
          },
          'labels': {
              'app': 'myapp',
              'environment': 'production'
          }
      }
  )

  result = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "id": "c7b9a6e5f8d3a1b2c3d4e5f6"
  }
  ```
</ResponseExample>

## Examples

### Bridge Network

Create a standard bridge network for container communication:

```json theme={null}
{
  "name": "app-network",
  "driver": "bridge",
  "ipam": {
    "config": [{
      "subnet": "172.18.0.0/16",
      "gateway": "172.18.0.1"
    }]
  }
}
```

### Overlay Network (Swarm)

Create an encrypted overlay network for swarm services:

```json theme={null}
{
  "name": "swarm-overlay",
  "driver": "overlay",
  "attachable": true,
  "ipam": {
    "config": [{
      "subnet": "10.0.9.0/24",
      "gateway": "10.0.9.1"
    }]
  },
  "options": {
    "encrypted": "true"
  }
}
```

### Macvlan Network

Create a macvlan network for containers that need physical network presence:

```json theme={null}
{
  "name": "macvlan-net",
  "driver": "macvlan",
  "ipam": {
    "config": [{
      "subnet": "192.168.1.0/24",
      "gateway": "192.168.1.1",
      "ipRange": "192.168.1.200/28"
    }]
  },
  "options": {
    "parent": "eth0",
    "macvlan_mode": "bridge"
  }
}
```

### Internal Network

Create an internal network with no external connectivity:

```json theme={null}
{
  "name": "backend-internal",
  "driver": "bridge",
  "internal": true,
  "ipam": {
    "config": [{
      "subnet": "172.19.0.0/16",
      "gateway": "172.19.0.1"
    }]
  }
}
```

## Notes

* Network names must be unique within the environment
* The `name` field is required; all other fields are optional
* Default driver is `bridge` if not specified
* IPAM configuration is optional; Docker will auto-assign if not provided
* Network creation is audited with the user, action, and network details
* Built-in networks (bridge, host, none) cannot be created as they already exist
* For overlay networks, Docker must be running in swarm mode