# Initialize a new swarm


[API catalog](/reference/api/) · [Docker Engine overview](/reference/api/engine/version/v1.57/) · [Product manual](https://docs.docker.com/engine/) · [OpenAPI specification](/reference/api/engine/version/v1.57.yaml)

API version: 1.57





`POST /swarm/init`



## Connection and access

[API connection and authentication guidance](/reference/api/engine/version/v1.57/#connection)


Server: `/v1.57`

Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement.

```json
null
```

## Example request

Replace placeholders and provide the required credentials or request body.

```console
curl \
  --request POST \
  --unix-socket "${DOCKER_SOCKET:-/var/run/docker.sock}" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "AdvertiseAddr": "192.168.1.1:2377",
  "DataPathPort": 4789,
  "DefaultAddrPool": [
    "10.10.0.0/8",
    "20.20.0.0/8"
  ],
  "ForceNewCluster": false,
  "ListenAddr": "0.0.0.0:2377",
  "Spec": {
    "CAConfig": {},
    "Dispatcher": {},
    "EncryptionConfig": {
      "AutoLockManagers": false
    },
    "Orchestration": {},
    "Raft": {}
  },
  "SubnetSize": 24
}' \
  'http://localhost/v1.57/swarm/init'
```



## Parameters

## Request and responses

### Request  application/json




Schema:

```json
{
  "example": {
    "AdvertiseAddr": "192.168.1.1:2377",
    "DataPathPort": 4789,
    "DefaultAddrPool": [
      "10.10.0.0/8",
      "20.20.0.0/8"
    ],
    "ForceNewCluster": false,
    "ListenAddr": "0.0.0.0:2377",
    "Spec": {
      "CAConfig": {},
      "Dispatcher": {},
      "EncryptionConfig": {
        "AutoLockManagers": false
      },
      "Orchestration": {},
      "Raft": {}
    },
    "SubnetSize": 24
  },
  "properties": {
    "AdvertiseAddr": {
      "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
      "type": "string"
    },
    "DataPathAddr": {
      "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other  nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
      "type": "string"
    },
    "DataPathPort": {
      "description": "DataPathPort specifies the data path port number for data traffic.\nAcceptable port range is 1024 to 49151.\nif no port is set or is set to 0, default port 4789 will be used.\n",
      "format": "uint32",
      "type": "integer"
    },
    "DefaultAddrPool": {
      "description": "Default Address Pool specifies default subnet pools for global\nscope networks.\n",
      "items": {
        "example": [
          "10.10.0.0/16",
          "20.20.0.0/16"
        ],
        "type": "string"
      },
      "type": "array"
    },
    "ForceNewCluster": {
      "description": "Force creation of a new swarm.",
      "type": "boolean"
    },
    "ListenAddr": {
      "description": "Listen address used for inter-manager communication, as well\nas determining the networking interface used for the VXLAN\nTunnel Endpoint (VTEP). This can either be an address/port\ncombination in the form `192.168.1.1:4567`, or an interface\nfollowed by a port number, like `eth0:4567`. If the port number\nis omitted, the default swarm listening port is used.\n",
      "type": "string"
    },
    "Spec": {
      "$ref": "#/components/schemas/SwarmSpec"
    },
    "SubnetSize": {
      "description": "SubnetSize specifies the subnet size of the networks created\nfrom the default subnet pool.\n",
      "format": "uint32",
      "type": "integer"
    }
  },
  "title": "SwarmInitRequest",
  "type": "object"
}
```









Schema example:
```json
{
  "AdvertiseAddr": "192.168.1.1:2377",
  "DataPathPort": 4789,
  "DefaultAddrPool": [
    "10.10.0.0/8",
    "20.20.0.0/8"
  ],
  "ForceNewCluster": false,
  "ListenAddr": "0.0.0.0:2377",
  "Spec": {
    "CAConfig": {},
    "Dispatcher": {},
    "EncryptionConfig": {
      "AutoLockManagers": false
    },
    "Orchestration": {},
    "Raft": {}
  },
  "SubnetSize": 24
}
```


### Request  text/plain




Schema:

```json
{
  "example": {
    "AdvertiseAddr": "192.168.1.1:2377",
    "DataPathPort": 4789,
    "DefaultAddrPool": [
      "10.10.0.0/8",
      "20.20.0.0/8"
    ],
    "ForceNewCluster": false,
    "ListenAddr": "0.0.0.0:2377",
    "Spec": {
      "CAConfig": {},
      "Dispatcher": {},
      "EncryptionConfig": {
        "AutoLockManagers": false
      },
      "Orchestration": {},
      "Raft": {}
    },
    "SubnetSize": 24
  },
  "properties": {
    "AdvertiseAddr": {
      "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
      "type": "string"
    },
    "DataPathAddr": {
      "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other  nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
      "type": "string"
    },
    "DataPathPort": {
      "description": "DataPathPort specifies the data path port number for data traffic.\nAcceptable port range is 1024 to 49151.\nif no port is set or is set to 0, default port 4789 will be used.\n",
      "format": "uint32",
      "type": "integer"
    },
    "DefaultAddrPool": {
      "description": "Default Address Pool specifies default subnet pools for global\nscope networks.\n",
      "items": {
        "example": [
          "10.10.0.0/16",
          "20.20.0.0/16"
        ],
        "type": "string"
      },
      "type": "array"
    },
    "ForceNewCluster": {
      "description": "Force creation of a new swarm.",
      "type": "boolean"
    },
    "ListenAddr": {
      "description": "Listen address used for inter-manager communication, as well\nas determining the networking interface used for the VXLAN\nTunnel Endpoint (VTEP). This can either be an address/port\ncombination in the form `192.168.1.1:4567`, or an interface\nfollowed by a port number, like `eth0:4567`. If the port number\nis omitted, the default swarm listening port is used.\n",
      "type": "string"
    },
    "Spec": {
      "$ref": "#/components/schemas/SwarmSpec"
    },
    "SubnetSize": {
      "description": "SubnetSize specifies the subnet size of the networks created\nfrom the default subnet pool.\n",
      "format": "uint32",
      "type": "integer"
    }
  },
  "title": "SwarmInitRequest",
  "type": "object"
}
```









Schema example:
```json
{
  "AdvertiseAddr": "192.168.1.1:2377",
  "DataPathPort": 4789,
  "DefaultAddrPool": [
    "10.10.0.0/8",
    "20.20.0.0/8"
  ],
  "ForceNewCluster": false,
  "ListenAddr": "0.0.0.0:2377",
  "Spec": {
    "CAConfig": {},
    "Dispatcher": {},
    "EncryptionConfig": {
      "AutoLockManagers": false
    },
    "Orchestration": {},
    "Raft": {}
  },
  "SubnetSize": 24
}
```


### Response 200 application/json

no error


Schema:

```json
{
  "description": "The node ID",
  "example": "7v2t30z9blmxuhnyo6s4cpenp",
  "type": "string"
}
```









Schema example:
```json
"7v2t30z9blmxuhnyo6s4cpenp"
```


### Response 200 text/plain

no error


Schema:

```json
{
  "description": "The node ID",
  "example": "7v2t30z9blmxuhnyo6s4cpenp",
  "type": "string"
}
```









Schema example:
```text
7v2t30z9blmxuhnyo6s4cpenp
```


### Response 400 application/json

bad parameter


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


### Response 500 application/json

server error


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


### Response 503 application/json

node is already part of a swarm


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


## Complete operation contract

```json
{
  "operationId": "SwarmInit",
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "example": {
            "AdvertiseAddr": "192.168.1.1:2377",
            "DataPathPort": 4789,
            "DefaultAddrPool": [
              "10.10.0.0/8",
              "20.20.0.0/8"
            ],
            "ForceNewCluster": false,
            "ListenAddr": "0.0.0.0:2377",
            "Spec": {
              "CAConfig": {},
              "Dispatcher": {},
              "EncryptionConfig": {
                "AutoLockManagers": false
              },
              "Orchestration": {},
              "Raft": {}
            },
            "SubnetSize": 24
          },
          "properties": {
            "AdvertiseAddr": {
              "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
              "type": "string"
            },
            "DataPathAddr": {
              "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other  nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
              "type": "string"
            },
            "DataPathPort": {
              "description": "DataPathPort specifies the data path port number for data traffic.\nAcceptable port range is 1024 to 49151.\nif no port is set or is set to 0, default port 4789 will be used.\n",
              "format": "uint32",
              "type": "integer"
            },
            "DefaultAddrPool": {
              "description": "Default Address Pool specifies default subnet pools for global\nscope networks.\n",
              "items": {
                "example": [
                  "10.10.0.0/16",
                  "20.20.0.0/16"
                ],
                "type": "string"
              },
              "type": "array"
            },
            "ForceNewCluster": {
              "description": "Force creation of a new swarm.",
              "type": "boolean"
            },
            "ListenAddr": {
              "description": "Listen address used for inter-manager communication, as well\nas determining the networking interface used for the VXLAN\nTunnel Endpoint (VTEP). This can either be an address/port\ncombination in the form `192.168.1.1:4567`, or an interface\nfollowed by a port number, like `eth0:4567`. If the port number\nis omitted, the default swarm listening port is used.\n",
              "type": "string"
            },
            "Spec": {
              "$ref": "#/components/schemas/SwarmSpec"
            },
            "SubnetSize": {
              "description": "SubnetSize specifies the subnet size of the networks created\nfrom the default subnet pool.\n",
              "format": "uint32",
              "type": "integer"
            }
          },
          "title": "SwarmInitRequest",
          "type": "object"
        }
      },
      "text/plain": {
        "schema": {
          "example": {
            "AdvertiseAddr": "192.168.1.1:2377",
            "DataPathPort": 4789,
            "DefaultAddrPool": [
              "10.10.0.0/8",
              "20.20.0.0/8"
            ],
            "ForceNewCluster": false,
            "ListenAddr": "0.0.0.0:2377",
            "Spec": {
              "CAConfig": {},
              "Dispatcher": {},
              "EncryptionConfig": {
                "AutoLockManagers": false
              },
              "Orchestration": {},
              "Raft": {}
            },
            "SubnetSize": 24
          },
          "properties": {
            "AdvertiseAddr": {
              "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
              "type": "string"
            },
            "DataPathAddr": {
              "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other  nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
              "type": "string"
            },
            "DataPathPort": {
              "description": "DataPathPort specifies the data path port number for data traffic.\nAcceptable port range is 1024 to 49151.\nif no port is set or is set to 0, default port 4789 will be used.\n",
              "format": "uint32",
              "type": "integer"
            },
            "DefaultAddrPool": {
              "description": "Default Address Pool specifies default subnet pools for global\nscope networks.\n",
              "items": {
                "example": [
                  "10.10.0.0/16",
                  "20.20.0.0/16"
                ],
                "type": "string"
              },
              "type": "array"
            },
            "ForceNewCluster": {
              "description": "Force creation of a new swarm.",
              "type": "boolean"
            },
            "ListenAddr": {
              "description": "Listen address used for inter-manager communication, as well\nas determining the networking interface used for the VXLAN\nTunnel Endpoint (VTEP). This can either be an address/port\ncombination in the form `192.168.1.1:4567`, or an interface\nfollowed by a port number, like `eth0:4567`. If the port number\nis omitted, the default swarm listening port is used.\n",
              "type": "string"
            },
            "Spec": {
              "$ref": "#/components/schemas/SwarmSpec"
            },
            "SubnetSize": {
              "description": "SubnetSize specifies the subnet size of the networks created\nfrom the default subnet pool.\n",
              "format": "uint32",
              "type": "integer"
            }
          },
          "title": "SwarmInitRequest",
          "type": "object"
        }
      }
    },
    "required": true,
    "x-codegen-request-body-name": "body"
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "description": "The node ID",
            "example": "7v2t30z9blmxuhnyo6s4cpenp",
            "type": "string"
          }
        },
        "text/plain": {
          "schema": {
            "description": "The node ID",
            "example": "7v2t30z9blmxuhnyo6s4cpenp",
            "type": "string"
          }
        }
      },
      "description": "no error"
    },
    "400": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "bad parameter"
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "server error"
    },
    "503": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "node is already part of a swarm"
    }
  },
  "summary": "Initialize a new swarm",
  "tags": [
    "Swarm"
  ]
}
```

## Referenced schemas

- [#/components/schemas/ErrorResponse](/reference/api/engine/version/v1.57/schemas/ErrorResponse/)

- [#/components/schemas/SwarmSpec](/reference/api/engine/version/v1.57/schemas/SwarmSpec/)




