--- title: "Create a container" method: POST path: "/containers/create" tags: ["Container"] --- # Create a container `POST /containers/create` ## Query parameters - `name` string ## Request body - object — Configuration for a container that is portable between hosts - `ArgsEscaped` boolean — Command is already escaped (Windows only) - `AttachStderr` boolean — Whether to attach to `stderr`. - `AttachStdin` boolean — Whether to attach to `stdin`. - `AttachStdout` boolean — Whether to attach to `stdout`. - `Cmd` union — Command to run specified as a string or an array of strings. - string[] - string - `Domainname` string — The domain name to use for the container. - `Entrypoint` union — 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`). - string[] - string - `Env` string[] — 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 — An object mapping ports to an empty object in the form: `{"/": {}}` - `Healthcheck` HealthConfig — A test to perform to check that the container is healthy. - `Interval` integer — The time to wait between checks in nanoseconds. It should be 0 or at least 1000000 (1 ms). 0 means inherit. - `Retries` integer — The number of consecutive failures needed to consider a container as unhealthy. 0 means inherit. - `StartPeriod` integer — 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` string[] — 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 — 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 — The hostname to use for the container, as a valid RFC 1123 hostname. - `Image` string — The name of the image to use when creating the container - `Labels` object — User-defined key/value metadata. - `MacAddress` string — MAC address of the container. - `NetworkDisabled` boolean — Disable networking for the container. - `OnBuild` string[] — `ONBUILD` metadata that were defined in the image's `Dockerfile`. - `OpenStdin` boolean — Open `stdin` - `Shell` string[] — Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell. - `StdinOnce` boolean — Close `stdin` after one attached client disconnects - `StopSignal` string — Signal to stop a container as a string or unsigned integer. - `StopTimeout` integer — Timeout to stop a container in seconds. - `Tty` boolean — Attach standard streams to a TTY, including `stdin` if it is not closed. - `User` string — The user that commands are run as inside the container. - `Volumes` object — An object mapping mount point paths inside the container to empty objects. - `additionalProperties` [object Object] - `WorkingDir` string — The working directory for commands to run in. - `HostConfig` HostConfig — Container configuration that depends on the host we are running on - `BlkioDeviceReadBps` ThrottleDevice[] — Limit read rate (bytes per second) from a device, in the form `[{"Path": "device_path", "Rate": rate}]`. - `Path` string — Device path - `Rate` integer — Rate - `BlkioDeviceReadIOps` ThrottleDevice[] — Limit read rate (IO per second) from a device, in the form `[{"Path": "device_path", "Rate": rate}]`. - `Path` string — Device path - `Rate` integer — Rate - `BlkioDeviceWriteBps` ThrottleDevice[] — Limit write rate (bytes per second) to a device, in the form `[{"Path": "device_path", "Rate": rate}]`. - `Path` string — Device path - `Rate` integer — Rate - `BlkioDeviceWriteIOps` ThrottleDevice[] — Limit write rate (IO per second) to a device, in the form `[{"Path": "device_path", "Rate": rate}]`. - `Path` string — Device path - `Rate` integer — Rate - `BlkioWeight` integer — Block IO weight (relative weight). - `BlkioWeightDevice` object[] — Block IO weight (relative device weight) in the form `[{"Path": "device_path", "Weight": weight}]`. - `Path` string - `Weight` integer - `CgroupParent` string — 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 — 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 — 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 — The length of a CPU period in microseconds. - `CpuQuota` integer — Microseconds of CPU time that the container can get in a CPU period. - `CpuRealtimePeriod` integer — The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks. - `CpuRealtimeRuntime` integer — The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks. - `CpuShares` integer — An integer value representing this container's relative CPU weight versus other containers. - `CpusetCpus` string — CPUs in which to allow execution (e.g., `0-3`, `0,1`) - `CpusetMems` string — Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. - `DeviceCgroupRules` string[] — a list of cgroup rules to apply to the container - `Devices` DeviceMapping[] — A list of devices to add to the container. - `CgroupPermissions` string - `PathInContainer` string - `PathOnHost` string - `DiskQuota` integer — Disk limit (in bytes). - `IOMaximumBandwidth` integer — Maximum IO in bytes per second for the container system drive (Windows only) - `IOMaximumIOps` integer — Maximum IOps for the container system drive (Windows only) - `KernelMemory` integer — Kernel memory limit in bytes. - `Memory` integer — Memory limit in bytes. - `MemoryReservation` integer — Memory soft limit in bytes. - `MemorySwap` integer — Total memory limit (memory + swap). Set as `-1` to enable unlimited swap. - `MemorySwappiness` integer — Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. - `NanoCPUs` integer — CPU quota in units of 10-9 CPUs. - `OomKillDisable` boolean — Disable OOM Killer for the container. - `PidsLimit` integer — Tune a container's pids limit. Set -1 for unlimited. - `Ulimits` object[] — A list of resource limits to set in the container. For example: `{"Name": "nofile", "Soft": 1024, "Hard": 2048}`" - `Hard` integer — Hard limit - `Name` string — Name of ulimit - `Soft` integer — Soft limit - `AutoRemove` boolean — Automatically remove the container when the container's process exits. This has no effect if `RestartPolicy` is set. - `Binds` string[] — 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` string[] — A list of kernel capabilities to add to the container. - `CapDrop` string[] — A list of kernel capabilities to drop from the container. - `Cgroup` string — Cgroup to use for the container. - `ConsoleSize` integer[] — Initial console size, as an `[height, width]` array. (Windows only) - `ContainerIDFile` string — Path to a file where the container ID is written - `Dns` string[] — A list of DNS servers for the container to use. - `DnsOptions` string[] — A list of DNS options. - `DnsSearch` string[] — A list of DNS search domains. - `ExtraHosts` string[] — A list of hostnames/IP mappings to add to the container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`. - `GroupAdd` string[] — A list of additional groups that the container process will run as. - `IpcMode` string — 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:"`: 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` 'default' | 'process' | 'hyperv' — Isolation technology of the container. (Windows only) - `Links` string[] — A list of links for the container in the form `container_name:alias`. - `LogConfig` object — The logging configuration for this container - `Config` object - `Type` 'json-file' | 'syslog' | 'journald' | 'gelf' | 'fluentd' | 'awslogs' | 'splunk' | 'etwlogs' | 'none' - `Mounts` Mount[] — Specification for mounts to be added to the container. - `BindOptions` object — Optional configuration for the `bind` type. - `Propagation` 'private' | 'rprivate' | 'shared' | 'rshared' | 'slave' | 'rslave' — A propagation mode with the value `[r]private`, `[r]shared`, or `[r]slave`. - `Consistency` string — The consistency requirement for the mount: `default`, `consistent`, `cached`, or `delegated`. - `ReadOnly` boolean — Whether the mount should be read-only. - `Source` string — Mount source (e.g. a volume name, a host path). - `Target` string — Container path. - `TmpfsOptions` object — Optional configuration for the `tmpfs` type. - `Mode` integer — The permission mode for the tmpfs mount in an integer. - `SizeBytes` integer — The size for the tmpfs mount in bytes. - `Type` 'bind' | 'volume' | 'tmpfs' — The mount type. Available types: - `bind` Mounts a file or directory from the host into the container. Must exist prior to creating the container. - `volume` Creates a volume with the given name and options (or uses a pre-existing volume with the same name and options). These are **not** removed when the container is removed. - `tmpfs` Create a tmpfs with the given options. The mount source cannot be specified for tmpfs. - `VolumeOptions` object — Optional configuration for the `volume` type. - `DriverConfig` object — Map of driver specific options - `Name` string — Name of the driver to use to create the volume. - `Options` object — key/value map of driver specific options. - `Labels` object — User-defined key/value metadata. - `NoCopy` boolean — Populate volume with data from the target. - `NetworkMode` string — Network mode to use for this container. Supported standard values are: `bridge`, `host`, `none`, and `container:`. Any other value is taken as a custom network's name to which this container should connect to. - `OomScoreAdj` integer — An integer value containing the score given to the container in order to tune OOM killer preferences. - `PidMode` string — Set the PID (Process) Namespace mode for the container. It can be either: - `"container:"`: joins another container's PID namespace - `"host"`: use the host's PID namespace inside the container - `PortBindings` object — A map of exposed container ports and the host port they should map to. - `Privileged` boolean — Gives the container full access to the host. - `PublishAllPorts` boolean — Allocates a random host port for all of a container's exposed ports. - `ReadonlyRootfs` boolean — Mount the container's root filesystem as read only. - `RestartPolicy` RestartPolicy — 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. - `MaximumRetryCount` integer — If `on-failure` is used, the number of times to retry before giving up - `Name` '' | 'always' | 'unless-stopped' | 'on-failure' — - Empty string means not to restart - `always` Always restart - `unless-stopped` Restart always except when the user has manually stopped the container - `on-failure` Restart only when the container exit code is non-zero - `Runtime` string — Runtime to use with this container. - `SecurityOpt` string[] — A list of string values to customize labels for MLS systems, such as SELinux. - `ShmSize` integer — Size of `/dev/shm` in bytes. If omitted, the system uses 64MB. - `StorageOpt` object — Storage driver options for this container, in the form `{"size": "120G"}`. - `Sysctls` object — A list of kernel parameters (sysctls) to set in the container. For example: `{"net.ipv4.ip_forward": "1"}` - `Tmpfs` object — 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 — UTS namespace to use for the container. - `UsernsMode` string — Sets the usernamespace mode for the container when usernamespace remapping option is enabled. - `VolumeDriver` string — Driver that this container uses to mount volumes. - `VolumesFrom` string[] — A list of volumes to inherit from another container, specified in the form `[:]`. - `NetworkingConfig` object — This container's networking configuration. - `EndpointsConfig` object — A mapping of network name to endpoint configuration for that network. ## Response `201` Container created successfully - object - `Id` string, required — The ID of the created container - `Warnings` string[], required — Warnings encountered when creating the container ## Other responses - `400` — bad parameter - `404` — no such container - `409` — conflict - `500` — server error --- [API](https://skmtc.net/docker/apis/engine.md) · [All operations](https://skmtc.net/docker/apis/engine/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/docker/engine/versions/400730735b03/schema)