Container

Create a container

post/containers/create

Query parameters

namestring

Assign the specified name to the container. Must match /?[a-zA-Z0-9][a-zA-Z0-9_.-]+.

platformstring

Platform in the format os[/arch[/variant]] used for image lookup.

When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a 404 status.

If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the Warnings field in the response, for example;

WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested

Request body

Hostnamestring

The hostname to use for the container, as a valid RFC 1123 hostname.

Domainnamestring

The domain name to use for the container.

Userstring

The user that commands are run as inside the container.

AttachStdinboolean

Whether to attach to stdin.

AttachStdoutboolean

Whether to attach to stdout.

AttachStderrboolean

Whether to attach to stderr.

ExposedPortsobject nullable

An object mapping ports to an empty object in the form:

{"<port>/<tcp|udp|sctp>": {}}

Ttyboolean

Attach standard streams to a TTY, including stdin if it is not closed.

OpenStdinboolean

Open stdin

StdinOnceboolean

Close stdin after one attached client disconnects

Envstring[]

A list of environment variables to set inside the container in the form ["VAR=value", ...]. A variable without = is removed from the environment, rather than to have an empty value.

Cmdstring[]

Command to run specified as a string or an array of strings.

ArgsEscapedboolean nullable

Command is already escaped (Windows only)

Imagestring

The name (or reference) of the image to use when creating the container, or which was used when the container was created.

Volumesobject

An object mapping mount point paths inside the container to empty objects.

WorkingDirstring

The working directory for commands to run in.

Entrypointstring[]

The entry point for the container as a string or an array of strings.

If the array consists of exactly one empty string ([""]) then the entry point is reset to system default (i.e., the entry point used by docker when there is no ENTRYPOINT instruction in the Dockerfile).

NetworkDisabledboolean nullable

Disable networking for the container.

MacAddressstring nullable

MAC address of the container.

Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.

OnBuildstring[] nullable

ONBUILD metadata that were defined in the image's Dockerfile.

Labelsobject

User-defined key/value metadata.

StopSignalstring nullable

Signal to stop a container as a string or unsigned integer.

StopTimeoutinteger nullable

Timeout to stop a container in seconds.

Shellstring[] nullable

Shell for when RUN, CMD, and ENTRYPOINT uses a shell.

Example request

{
  "Hostname": "",
  "Domainname": "",
  "User": "",
  "AttachStdin": false,
  "AttachStdout": true,
  "AttachStderr": true,
  "Tty": false,
  "OpenStdin": false,
  "StdinOnce": false,
  "Env": [
    "FOO=bar",
    "BAZ=quux"
  ],
  "Cmd": [
    "date"
  ],
  "Entrypoint": "",
  "Image": "ubuntu",
  "Labels": {
    "com.example.vendor": "Acme",
    "com.example.license": "GPL",
    "com.example.version": "1.0"
  },
  "Volumes": {
    "/volumes/data": {}
  },
  "WorkingDir": "",
  "NetworkDisabled": false,
  "MacAddress": "12:34:56:78:9a:bc",
  "ExposedPorts": {
    "22/tcp": {}
  },
  "StopSignal": "SIGTERM",
  "StopTimeout": 10,
  "HostConfig": {
    "Binds": [
      "/tmp:/tmp"
    ],
    "Links": [
      "redis3:redis"
    ],
    "Memory": 0,
    "MemorySwap": 0,
    "MemoryReservation": 0,
    "NanoCpus": 500000,
    "CpuPercent": 80,
    "CpuShares": 512,
    "CpuPeriod": 100000,
    "CpuRealtimePeriod": 1000000,
    "CpuRealtimeRuntime": 10000,
    "CpuQuota": 50000,
    "CpusetCpus": "0,1",
    "CpusetMems": "0,1",
    "MaximumIOps": 0,
    "MaximumIOBps": 0,
    "BlkioWeight": 300,
    "BlkioWeightDevice": [
      {}
    ],
    "BlkioDeviceReadBps": [
      {}
    ],
    "BlkioDeviceReadIOps": [
      {}
    ],
    "BlkioDeviceWriteBps": [
      {}
    ],
    "BlkioDeviceWriteIOps": [
      {}
    ],
    "DeviceRequests": [
      {
        "Driver": "nvidia",
        "Count": -1,
        "DeviceIDs\"": [
          "0",
          "1",
          "GPU-fef8089b-4820-abfc-e83e-94318197576e"
        ],
        "Capabilities": [
          [
            "gpu",
            "nvidia",
            "compute"
          ]
        ],
        "Options": {
          "property1": "string",
          "property2": "string"
        }
      }
    ],
    "MemorySwappiness": 60,
    "OomKillDisable": false,
    "OomScoreAdj": 500,
    "PidMode": "",
    "PidsLimit": 0,
    "PortBindings": {
      "22/tcp": [
        {
          "HostPort": "11022"
        }
      ]
    },
    "PublishAllPorts": false,
    "Privileged": false,
    "ReadonlyRootfs": false,
    "Dns": [
      "8.8.8.8"
    ],
    "DnsOptions": [
      ""
    ],
    "DnsSearch": [
      ""
    ],
    "VolumesFrom": [
      "parent",
      "other:ro"
    ],
    "CapAdd": [
      "NET_ADMIN"
    ],
    "CapDrop": [
      "MKNOD"
    ],
    "GroupAdd": [
      "newgroup"
    ],
    "RestartPolicy": {
      "Name": "",
      "MaximumRetryCount": 0
    },
    "AutoRemove": true,
    "NetworkMode": "bridge",
    "Devices": [],
    "Ulimits": [
      {}
    ],
    "LogConfig": {
      "Type": "json-file",
      "Config": {}
    },
    "SecurityOpt": [],
    "StorageOpt": {},
    "CgroupParent": "",
    "VolumeDriver": "",
    "ShmSize": 67108864
  },
  "NetworkingConfig": {
    "EndpointsConfig": {
      "isolated_nw": {
        "IPAMConfig": {
          "IPv4Address": "172.20.30.33",
          "IPv6Address": "2001:db8:abcd::3033",
          "LinkLocalIPs": [
            "169.254.34.68",
            "fe80::3468"
          ]
        },
        "Links": [
          "container_1",
          "container_2"
        ],
        "Aliases": [
          "server_x",
          "server_y"
        ]
      },
      "database_nw": {}
    }
  }
}

Response

Container created successfully

Idstring required

The ID of the created container

Warningsstring[] required

Warnings encountered when creating the container

Example response

{
  "Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
  "Warnings": []
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.