# Attach to a container


[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 /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](https://docs.docker.com/engine/reference/commandline/attach/)
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`](/reference/api/engine/version/v1.57/operations/ContainerCreate/),
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:

```go
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`](/reference/api/engine/version/v1.57/operations/ContainerCreate/),
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`.


## 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
```


This operation upgrades the HTTP connection. Use a client that supports the protocol described for this operation.


## Parameters

### id

Location: path. Required: yes.

ID or name of the container

```json
{
  "description": "ID or name of the container",
  "in": "path",
  "name": "id",
  "pointer": "/paths/~1containers~1{id}~1attach/post/parameters/0",
  "required": true,
  "schema": {
    "type": "string"
  }
}
```

### detachKeys

Location: query. Required: no.

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 `_`.


```json
{
  "description": "Override the key sequence for detaching a container.Format is a single\ncharacter `[a-Z]` or `ctrl-\u003cvalue\u003e` where `\u003cvalue\u003e` is one of: `a-z`,\n`@`, `^`, `[`, `,` or `_`.\n",
  "in": "query",
  "name": "detachKeys",
  "pointer": "/paths/~1containers~1{id}~1attach/post/parameters/1",
  "schema": {
    "type": "string"
  }
}
```

### logs

Location: query. Required: no.

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.


```json
{
  "description": "Replay previous logs from the container.\n\nThis is useful for attaching to a container that has started and you\nwant to output everything since the container started.\n\nIf `stream` is also enabled, once all the previous output has been\nreturned, it will seamlessly transition into streaming current\noutput.\n",
  "in": "query",
  "name": "logs",
  "pointer": "/paths/~1containers~1{id}~1attach/post/parameters/2",
  "schema": {
    "default": false,
    "type": "boolean"
  }
}
```

### stream

Location: query. Required: no.

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


```json
{
  "description": "Stream attached streams from the time the request was made onwards.\n",
  "in": "query",
  "name": "stream",
  "pointer": "/paths/~1containers~1{id}~1attach/post/parameters/3",
  "schema": {
    "default": false,
    "type": "boolean"
  }
}
```

### stdin

Location: query. Required: no.

Attach to `stdin`

```json
{
  "description": "Attach to `stdin`",
  "in": "query",
  "name": "stdin",
  "pointer": "/paths/~1containers~1{id}~1attach/post/parameters/4",
  "schema": {
    "default": false,
    "type": "boolean"
  }
}
```

### stdout

Location: query. Required: no.

Attach to `stdout`

```json
{
  "description": "Attach to `stdout`",
  "in": "query",
  "name": "stdout",
  "pointer": "/paths/~1containers~1{id}~1attach/post/parameters/5",
  "schema": {
    "default": false,
    "type": "boolean"
  }
}
```

### stderr

Location: query. Required: no.

Attach to `stderr`

```json
{
  "description": "Attach to `stderr`",
  "in": "query",
  "name": "stderr",
  "pointer": "/paths/~1containers~1{id}~1attach/post/parameters/6",
  "schema": {
    "default": false,
    "type": "boolean"
  }
}
```

## Request and responses

### Response 101 application/vnd.docker.multiplexed-stream

no error, hints proxy about hijacking











### Response 101 application/vnd.docker.raw-stream

no error, hints proxy about hijacking











### Response 200 application/vnd.docker.multiplexed-stream

no error, no upgrade header found











### Response 200 application/vnd.docker.raw-stream

no error, no upgrade header found











### Response 400 application/json

bad parameter


Schema:

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









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


### Response 404 application/json

no such container


Schema:

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









Example:
```json
{
  "message": "No such container: c2ada9df5af8"
}
```


### Response 500 application/json

server error


Schema:

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









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


## Complete operation contract

```json
{
  "description": "Attach to a container to read its output or send it input. You can attach\nto the same container multiple times and you can reattach to containers\nthat have been detached.\n\nEither the `stream` or `logs` parameter must be `true` for this endpoint\nto do anything.\n\nSee the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/)\nfor more details.\n\n### Hijacking\n\nThis endpoint hijacks the HTTP connection to transport `stdin`, `stdout`,\nand `stderr` on the same socket.\n\nThis is the response from the daemon for an attach request:\n\n```\nHTTP/1.1 200 OK\nContent-Type: application/vnd.docker.raw-stream\n\n[STREAM]\n```\n\nAfter the headers and two new lines, the TCP connection can now be used\nfor raw, bidirectional communication between the client and server.\n\nTo hint potential proxies about connection hijacking, the Docker client\ncan also optionally send connection upgrade headers.\n\nFor example, the client sends this request to upgrade the connection:\n\n```\nPOST /containers/16253994b7c4/attach?stream=1\u0026stdout=1 HTTP/1.1\nUpgrade: tcp\nConnection: Upgrade\n```\n\nThe Docker daemon will respond with a `101 UPGRADED` response, and will\nsimilarly follow with the raw stream:\n\n```\nHTTP/1.1 101 UPGRADED\nContent-Type: application/vnd.docker.raw-stream\nConnection: Upgrade\nUpgrade: tcp\n\n[STREAM]\n```\n\n### Stream format\n\nWhen the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate),\nthe HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream\nand the stream over the hijacked connected is multiplexed to separate out\n`stdout` and `stderr`. The stream consists of a series of frames, each\ncontaining a header and a payload.\n\nThe header contains the information which the stream writes (`stdout` or\n`stderr`). It also contains the size of the associated frame encoded in\nthe last four bytes (`uint32`).\n\nIt is encoded on the first eight bytes like this:\n\n```go\nheader := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}\n```\n\n`STREAM_TYPE` can be:\n\n- 0: `stdin` (is written on `stdout`)\n- 1: `stdout`\n- 2: `stderr`\n\n`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size\nencoded as big endian.\n\nFollowing the header is the payload, which is the specified number of\nbytes of `STREAM_TYPE`.\n\nThe simplest way to implement this protocol is the following:\n\n1. Read 8 bytes.\n2. Choose `stdout` or `stderr` depending on the first byte.\n3. Extract the frame size from the last four bytes.\n4. Read the extracted size and output it on the correct output.\n5. Goto 1.\n\n### Stream format when using a TTY\n\nWhen the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate),\nthe stream is not multiplexed. The data exchanged over the hijacked\nconnection is simply the raw data from the process PTY and client's\n`stdin`.\n",
  "operationId": "ContainerAttach",
  "parameters": [
    {
      "description": "ID or name of the container",
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Override the key sequence for detaching a container.Format is a single\ncharacter `[a-Z]` or `ctrl-\u003cvalue\u003e` where `\u003cvalue\u003e` is one of: `a-z`,\n`@`, `^`, `[`, `,` or `_`.\n",
      "in": "query",
      "name": "detachKeys",
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Replay previous logs from the container.\n\nThis is useful for attaching to a container that has started and you\nwant to output everything since the container started.\n\nIf `stream` is also enabled, once all the previous output has been\nreturned, it will seamlessly transition into streaming current\noutput.\n",
      "in": "query",
      "name": "logs",
      "schema": {
        "default": false,
        "type": "boolean"
      }
    },
    {
      "description": "Stream attached streams from the time the request was made onwards.\n",
      "in": "query",
      "name": "stream",
      "schema": {
        "default": false,
        "type": "boolean"
      }
    },
    {
      "description": "Attach to `stdin`",
      "in": "query",
      "name": "stdin",
      "schema": {
        "default": false,
        "type": "boolean"
      }
    },
    {
      "description": "Attach to `stdout`",
      "in": "query",
      "name": "stdout",
      "schema": {
        "default": false,
        "type": "boolean"
      }
    },
    {
      "description": "Attach to `stderr`",
      "in": "query",
      "name": "stderr",
      "schema": {
        "default": false,
        "type": "boolean"
      }
    }
  ],
  "responses": {
    "101": {
      "content": {
        "application/vnd.docker.multiplexed-stream": {},
        "application/vnd.docker.raw-stream": {}
      },
      "description": "no error, hints proxy about hijacking"
    },
    "200": {
      "content": {
        "application/vnd.docker.multiplexed-stream": {},
        "application/vnd.docker.raw-stream": {}
      },
      "description": "no error, no upgrade header found"
    },
    "400": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "bad parameter"
    },
    "404": {
      "content": {
        "application/json": {
          "example": {
            "message": "No such container: c2ada9df5af8"
          },
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "no such container"
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "server error"
    }
  },
  "summary": "Attach to a container",
  "tags": [
    "Container"
  ]
}
```

## Referenced schemas

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




