Attach to a container Run in API Explorer

POST /containers/{id}/attach

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the stream or logs parameter must be true for this endpoint to do anything.

See the documentation for the docker attach command for more details.

Hijacking

This endpoint hijacks the HTTP connection to transport stdin, stdout, and stderr on the same socket.

This is the response from the daemon for an attach request:

HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade

The Docker daemon will respond with a 101 UPGRADED response, and will similarly follow with the raw stream:

HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]

Stream format

When the TTY setting is disabled in POST /containers/create, the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out stdout and stderr. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (stdout or stderr). It also contains the size of the associated frame encoded in the last four bytes (uint32).

It is encoded on the first eight bytes like this:

header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}

STREAM_TYPE can be:

  • 0: stdin (is written on stdout)
  • 1: stdout
  • 2: stderr

SIZE1, SIZE2, SIZE3, SIZE4 are the four bytes of the uint32 size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of STREAM_TYPE.

The simplest way to implement this protocol is the following:

  1. Read 8 bytes.
  2. Choose stdout or stderr depending on the first byte.
  3. Extract the frame size from the last four bytes.
  4. Read the extracted size and output it on the correct output.
  5. Goto 1.

Stream format when using a TTY

When the TTY setting is enabled in POST /containers/create, the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's stdin.

Path parameters

  • id string Required

    ID or name of the container

Query parameters

  • detachKeys string

    Override the key sequence for detaching a container.Format is a single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _.

  • logs boolean

    Replay previous logs from the container.

    This is useful for attaching to a container that has started and you want to output everything since the container started.

    If stream is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output.

    Default value is false.

  • stream boolean

    Stream attached streams from the time the request was made onwards.

    Default value is false.

  • stdin boolean

    Attach to stdin

    Default value is false.

  • stdout boolean

    Attach to stdout

    Default value is false.

  • stderr boolean

    Attach to stderr

    Default value is false.

Responses

POST /containers/{id}/attach 
curl \
 --request POST 'http://api.example.com/v1.49/containers/{id}/attach'
Response examples (400) 
{
  "message": "Something went wrong."
}
Response examples (404) 
{
  "message": "No such container: c2ada9df5af8"
}
Response examples (500) 
{
  "message": "Something went wrong."
}