Docker Engine API
  1. Container
Docker Engine API
  • System
    • Ping
      GET
    • Check auth configuration
      POST
    • Monitor events
      GET
    • Get system information
      GET
    • Get data usage information
      GET
    • Get version
      GET
  • Image
    • Build an image
    • Delete builder cache
    • Create a new image from a container
    • Create an image
    • Export several images
    • List Images
    • Import images
    • Delete unused images
    • Search images
    • Remove an image
    • Export an image
    • Get the history of an image
    • Inspect an image
    • Push an image
    • Tag an image
  • Config
    • List configs
    • Create a config
    • Delete a config
    • Inspect a config
    • Update a Config
  • Container
    • Create a container
      POST
    • List containers
      GET
    • Delete stopped containers
      POST
    • Remove a container
      DELETE
    • Get an archive of a filesystem resource in a container
      GET
    • Get information about files in a container
      HEAD
    • Extract an archive of files or folders to a directory in a container
      PUT
    • Attach to a container
      POST
    • Attach to a container via a websocket
      GET
    • Get changes on a container’s filesystem
      GET
    • Export a container
      GET
    • Inspect a container
      GET
    • Kill a container
      POST
    • Get container logs
      GET
    • Pause a container
      POST
    • Rename a container
      POST
    • Resize a container TTY
      POST
    • Restart a container
      POST
    • Start a container
      POST
    • Get container stats based on resource usage
      GET
    • Stop a container
      POST
    • List processes running inside a container
      GET
    • Unpause a container
      POST
    • Update a container
      POST
    • Wait for a container
      POST
  • Exec
    • Create an exec instance
    • Inspect an exec instance
    • Resize an exec instance
    • Start an exec instance
  • Distribution
    • Get image information from the registry
  • Network
    • List networks
    • Create a network
    • Delete unused networks
    • Remove a network
    • Inspect a network
    • Connect a container to a network
    • Disconnect a container from a network
  • Node
    • List nodes
    • Delete a node
    • Inspect a node
    • Update a node
  • Plugin
    • List plugins
    • Create a plugin
    • Get plugin privileges
    • Install a plugin
    • Remove a plugin
    • Disable a plugin
    • Enable a plugin
    • Inspect a plugin
    • Push a plugin
    • Configure a plugin
    • Upgrade a plugin
  • Secret
    • List secrets
    • Create a secret
    • Delete a secret
    • Inspect a secret
    • Update a Secret
  • Service
    • List services
    • Create a service
    • Delete a service
    • Inspect a service
    • Get service logs
    • Update a service
  • Session (experimental)
    • Initialize interactive session
  • Swarm
    • Inspect swarm
    • Initialize a new swarm
    • Join an existing swarm
    • Leave a swarm
    • Unlock a locked manager
    • Get the unlock key
    • Update a swarm
  • Task
    • List tasks
    • Inspect a task
  • Volume
    • List volumes
    • Create a volume
    • Delete unused volumes
    • Remove a volume
    • Inspect a volume
  • Get task logs
    GET
  1. Container

Create a container

/v1.33
/v1.33
/v1.33
/v1.33
POST
/containers/create
Container
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST '/v1.33/containers/create' \
--header 'Content-Type: application/json' \
--data-raw '{
    "AttachStderr": true,
    "AttachStdin": false,
    "AttachStdout": true,
    "Cmd": [
        "date"
    ],
    "Domainname": "",
    "Entrypoint": "",
    "Env": [
        "FOO=bar",
        "BAZ=quux"
    ],
    "ExposedPorts": {
        "22/tcp": {}
    },
    "HostConfig": {
        "AutoRemove": true,
        "Binds": [
            "/tmp:/tmp"
        ],
        "BlkioDeviceReadBps": [
            {}
        ],
        "BlkioDeviceReadIOps": [
            {}
        ],
        "BlkioDeviceWriteBps": [
            {}
        ],
        "BlkioDeviceWriteIOps": [
            {}
        ],
        "BlkioWeight": 300,
        "BlkioWeightDevice": [
            {}
        ],
        "CapAdd": [
            "NET_ADMIN"
        ],
        "CapDrop": [
            "MKNOD"
        ],
        "CgroupParent": "",
        "CpuPercent": 80,
        "CpuPeriod": 100000,
        "CpuQuota": 50000,
        "CpuRealtimePeriod": 1000000,
        "CpuRealtimeRuntime": 10000,
        "CpuShares": 512,
        "CpusetCpus": "0,1",
        "CpusetMems": "0,1",
        "Devices": [],
        "Dns": [
            "8.8.8.8"
        ],
        "DnsOptions": [
            ""
        ],
        "DnsSearch": [
            ""
        ],
        "GroupAdd": [
            "newgroup"
        ],
        "KernelMemory": 0,
        "Links": [
            "redis3:redis"
        ],
        "LogConfig": {
            "Config": {},
            "Type": "json-file"
        },
        "MaximumIOBps": 0,
        "MaximumIOps": 0,
        "Memory": 0,
        "MemoryReservation": 0,
        "MemorySwap": 0,
        "MemorySwappiness": 60,
        "NanoCPUs": 500000,
        "NetworkMode": "bridge",
        "OomKillDisable": false,
        "OomScoreAdj": 500,
        "PidMode": "",
        "PidsLimit": -1,
        "PortBindings": {
            "22/tcp": [
                {
                    "HostPort": "11022"
                }
            ]
        },
        "Privileged": false,
        "PublishAllPorts": false,
        "ReadonlyRootfs": false,
        "RestartPolicy": {
            "MaximumRetryCount": 0,
            "Name": ""
        },
        "SecurityOpt": [],
        "ShmSize": 67108864,
        "StorageOpt": {},
        "Ulimits": [
            {}
        ],
        "VolumeDriver": "",
        "VolumesFrom": [
            "parent",
            "other:ro"
        ]
    },
    "Hostname": "",
    "Image": "ubuntu",
    "Labels": {
        "com.example.license": "GPL",
        "com.example.vendor": "Acme",
        "com.example.version": "1.0"
    },
    "MacAddress": "12:34:56:78:9a:bc",
    "NetworkDisabled": false,
    "NetworkingConfig": {
        "EndpointsConfig": {
            "isolated_nw": {
                "Aliases": [
                    "server_x",
                    "server_y"
                ],
                "IPAMConfig": {
                    "IPv4Address": "172.20.30.33",
                    "IPv6Address": "2001:db8:abcd::3033",
                    "LinkLocalIPs": [
                        "169.254.34.68",
                        "fe80::3468"
                    ]
                },
                "Links": [
                    "container_1",
                    "container_2"
                ]
            }
        }
    },
    "OpenStdin": false,
    "StdinOnce": false,
    "StopSignal": "SIGTERM",
    "StopTimeout": 10,
    "Tty": false,
    "User": "",
    "Volumes": {
        "/volumes/data": {}
    },
    "WorkingDir": ""
}'
Response Response Example
201 - response
{
    "Id": "e90e34656806",
    "Warnings": []
}

Request

Query Params
name
string 
optional
Assign the specified name to the container. Must match /?[a-zA-Z0-9_-]+.
Body Params application/json
Configuration for a container that is portable between hosts
ArgsEscaped
boolean 
optional
Command is already escaped (Windows only)
AttachStderr
boolean 
optional
Whether to attach to stderr.
Default:
true
AttachStdin
boolean 
optional
Whether to attach to stdin.
Default:
false
AttachStdout
boolean 
optional
Whether to attach to stdout.
Default:
true
Cmd
optional
Command to run specified as a string or an array of strings.
One of
Domainname
string 
optional
The domain name to use for the container.
Entrypoint
optional
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).
One of
Env
array[string]
optional
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.
ExposedPorts
object 
optional
An object mapping ports to an empty object in the form:
{"<port>/<tcp|udp>": {}}
Healthcheck
object 
HealthConfig
optional
A test to perform to check that the container is healthy.
Interval
integer 
optional
The time to wait between checks in nanoseconds. It should be 0 or at least 1000000 (1 ms). 0 means inherit.
Retries
integer 
optional
The number of consecutive failures needed to consider a container as unhealthy. 0 means inherit.
StartPeriod
integer 
optional
Start period for the container to initialize before starting health-retries countdown in nanoseconds. It should be 0 or at least 1000000 (1 ms). 0 means inherit.
Test
array[string]
optional
The test to perform. Possible values are:
[] inherit healthcheck from image or parent image
["NONE"] disable healthcheck
["CMD", args...] exec arguments directly
["CMD-SHELL", command] run command with system's default shell
Timeout
integer 
optional
The time to wait before considering the check to have hung. It should be 0 or at least 1000000 (1 ms). 0 means inherit.
Hostname
string 
optional
The hostname to use for the container, as a valid RFC 1123 hostname.
Image
string 
optional
The name of the image to use when creating the container
Labels
object 
optional
User-defined key/value metadata.
MacAddress
string 
optional
MAC address of the container.
NetworkDisabled
boolean 
optional
Disable networking for the container.
OnBuild
array[string]
optional
ONBUILD metadata that were defined in the image's Dockerfile.
OpenStdin
boolean 
optional
Open stdin
Default:
false
Shell
array[string]
optional
Shell for when RUN, CMD, and ENTRYPOINT uses a shell.
StdinOnce
boolean 
optional
Close stdin after one attached client disconnects
Default:
false
StopSignal
string 
optional
Signal to stop a container as a string or unsigned integer.
Default:
SIGTERM
StopTimeout
integer 
optional
Timeout to stop a container in seconds.
Default:
10
Tty
boolean 
optional
Attach standard streams to a TTY, including stdin if it is not closed.
Default:
false
User
string 
optional
The user that commands are run as inside the container.
Volumes
object 
optional
An object mapping mount point paths inside the container to empty objects.
additionalProperties
object 
optional
Allowed value:
{}
Default:
{}
WorkingDir
string 
optional
The working directory for commands to run in.
HostConfig
object 
HostConfig
optional
Container configuration that depends on the host we are running on
BlkioDeviceReadBps
array[object (ThrottleDevice) {2}] 
optional
Limit read rate (bytes per second) from a device, in the form [{"Path": "device_path", "Rate": rate}].
BlkioDeviceReadIOps
array[object (ThrottleDevice) {2}] 
optional
Limit read rate (IO per second) from a device, in the form [{"Path": "device_path", "Rate": rate}].
BlkioDeviceWriteBps
array[object (ThrottleDevice) {2}] 
optional
Limit write rate (bytes per second) to a device, in the form [{"Path": "device_path", "Rate": rate}].
BlkioDeviceWriteIOps
array[object (ThrottleDevice) {2}] 
optional
Limit write rate (IO per second) to a device, in the form [{"Path": "device_path", "Rate": rate}].
BlkioWeight
integer 
optional
Block IO weight (relative weight).
>= 0<= 1000
BlkioWeightDevice
array [object {2}] 
optional
Block IO weight (relative device weight) in the form [{"Path": "device_path", "Weight": weight}].
CgroupParent
string 
optional
Path to cgroups under which the container's cgroup is created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups are created if they do not already exist.
CpuCount
integer <int64>
optional
The number of usable CPUs (Windows only).
On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
CpuPercent
integer <int64>
optional
The usable percentage of the available CPUs (Windows only).
On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
CpuPeriod
integer <int64>
optional
The length of a CPU period in microseconds.
CpuQuota
integer <int64>
optional
Microseconds of CPU time that the container can get in a CPU period.
CpuRealtimePeriod
integer <int64>
optional
The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.
CpuRealtimeRuntime
integer <int64>
optional
The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.
CpuShares
integer 
optional
An integer value representing this container's relative CPU weight versus other containers.
CpusetCpus
string 
optional
CPUs in which to allow execution (e.g., 0-3, 0,1)
Example:
0-3
CpusetMems
string 
optional
Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
DeviceCgroupRules
array[string]
optional
a list of cgroup rules to apply to the container
Devices
array[object (DeviceMapping) {3}] 
optional
A list of devices to add to the container.
DiskQuota
integer <int64>
optional
Disk limit (in bytes).
IOMaximumBandwidth
integer <int64>
optional
Maximum IO in bytes per second for the container system drive (Windows only)
IOMaximumIOps
integer <int64>
optional
Maximum IOps for the container system drive (Windows only)
KernelMemory
integer <int64>
optional
Kernel memory limit in bytes.
Memory
integer 
optional
Memory limit in bytes.
Default:
0
MemoryReservation
integer <int64>
optional
Memory soft limit in bytes.
MemorySwap
integer <int64>
optional
Total memory limit (memory + swap). Set as -1 to enable unlimited swap.
MemorySwappiness
integer <int64>
optional
Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
>= 0<= 100
NanoCPUs
integer <int64>
optional
CPU quota in units of 10-9 CPUs.
OomKillDisable
boolean 
optional
Disable OOM Killer for the container.
PidsLimit
integer <int64>
optional
Tune a container's pids limit. Set -1 for unlimited.
Ulimits
array [object {3}] 
optional
A list of resource limits to set in the container. For example: {"Name": "nofile", "Soft": 1024, "Hard": 2048}"
AutoRemove
boolean 
optional
Automatically remove the container when the container's process exits. This has no effect if RestartPolicy is set.
Binds
array[string]
optional
A list of volume bindings for this container. Each volume binding is a string in one of these forms:
host-src:container-dest to bind-mount a host path into the container. Both host-src, and container-dest must be an absolute path.
host-src:container-dest:ro to make the bind mount read-only inside the container. Both host-src, and container-dest must be an absolute path.
volume-name:container-dest to bind-mount a volume managed by a volume driver into the container. container-dest must be an absolute path.
volume-name:container-dest:ro to mount the volume read-only inside the container. container-dest must be an absolute path.
CapAdd
array[string]
optional
A list of kernel capabilities to add to the container.
CapDrop
array[string]
optional
A list of kernel capabilities to drop from the container.
Cgroup
string 
optional
Cgroup to use for the container.
ConsoleSize
array[integer]
optional
Initial console size, as an [height, width] array. (Windows only)
>= 2 items<= 2 items
ContainerIDFile
string 
optional
Path to a file where the container ID is written
Dns
array[string]
optional
A list of DNS servers for the container to use.
DnsOptions
array[string]
optional
A list of DNS options.
DnsSearch
array[string]
optional
A list of DNS search domains.
ExtraHosts
array[string]
optional
A list of hostnames/IP mappings to add to the container's /etc/hosts file. Specified in the form ["hostname:IP"].
GroupAdd
array[string]
optional
A list of additional groups that the container process will run as.
IpcMode
string 
optional
IPC sharing mode for the container. Possible values are:
"none": own private IPC namespace, with /dev/shm not mounted
"private": own private IPC namespace
"shareable": own private IPC namespace, with a possibility to share it with other containers
"container:<name|id>": join another (shareable) container's IPC namespace
"host": use the host system's IPC namespace
If not specified, daemon default is used, which can either be "private"
or "shareable", depending on daemon version and configuration.
Isolation
enum<string> 
optional
Isolation technology of the container. (Windows only)
Allowed values:
defaultprocesshyperv
Links
array[string]
optional
A list of links for the container in the form container_name:alias.
LogConfig
object 
optional
The logging configuration for this container
Mounts
array[object (Mount) {8}] 
optional
Specification for mounts to be added to the container.
NetworkMode
string 
optional
Network mode to use for this container. Supported standard values are: bridge, host, none, and container:<name|id>. Any other value is taken as a custom network's name to which this container should connect to.
OomScoreAdj
integer 
optional
An integer value containing the score given to the container in order to tune OOM killer preferences.
Example:
500
PidMode
string 
optional
Set the PID (Process) Namespace mode for the container. It can be either:
"container:<name|id>": joins another container's PID namespace
"host": use the host's PID namespace inside the container
PortBindings
object 
optional
A map of exposed container ports and the host port they should map to.
Privileged
boolean 
optional
Gives the container full access to the host.
PublishAllPorts
boolean 
optional
Allocates a random host port for all of a container's exposed ports.
ReadonlyRootfs
boolean 
optional
Mount the container's root filesystem as read only.
RestartPolicy
object 
RestartPolicy
optional
The behavior to apply when the container exits. The default is not to restart.
An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.
Runtime
string 
optional
Runtime to use with this container.
SecurityOpt
array[string]
optional
A list of string values to customize labels for MLS systems, such as SELinux.
ShmSize
integer 
optional
Size of /dev/shm in bytes. If omitted, the system uses 64MB.
>= 0
StorageOpt
object 
optional
Storage driver options for this container, in the form {"size": "120G"}.
Sysctls
object 
optional
A list of kernel parameters (sysctls) to set in the container. For example: {"net.ipv4.ip_forward": "1"}
Tmpfs
object 
optional
A map of container directories which should be replaced by tmpfs mounts, and their corresponding mount options. For example: { "/run": "rw,noexec,nosuid,size=65536k" }.
UTSMode
string 
optional
UTS namespace to use for the container.
UsernsMode
string 
optional
Sets the usernamespace mode for the container when usernamespace remapping option is enabled.
VolumeDriver
string 
optional
Driver that this container uses to mount volumes.
VolumesFrom
array[string]
optional
A list of volumes to inherit from another container, specified in the form <container name>[:<ro|rw>].
NetworkingConfig
object 
optional
This container's networking configuration.
EndpointsConfig
object 
optional
A mapping of network name to endpoint configuration for that network.
Examples

Responses

🟢201Container created successfully
application/json
Body
Id
string 
required
The ID of the created container
Warnings
array[string]
required
Warnings encountered when creating the container
🟠400bad parameter
🟠404no such container
🟠409conflict
🔴500server error
Modified at 2022-09-10 17:56:06
Previous
Update a Config
Next
List containers
Built with