> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Using ngrok with Docker

> Learn how to use ngrok with Docker to expose your local applications and services to the internet.

export const YouTubeEmbed = ({className, title, videoId, ...props}) => {
  return <div className={`relative aspect-video mb-3 ${className}`} {...props}>
      <iframe src={`https://www.youtube.com/embed/${videoId}`} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen className="absolute inset-0 w-full h-full" title={title} />
    </div>;
};

<Tip>
  For detailed instructions on using ngrok with Kubernetes, check out the [k8s quickstart](/k8s/).
</Tip>

ngrok provides [pre-built docker images](https://hub.docker.com/r/ngrok/ngrok) for the ngrok Agent with instructions for getting started. An example command for starting a tunnel to port `80` on the host machine looks like this.

<Tabs>
  <Tab title="Debian Linux">
    ```bash theme={null}
    docker run --net=host -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http 80
    ```
  </Tab>

  <Tab title="Windows or Mac">
    ```bash theme={null}
    docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http host.docker.internal:80
    ```

    For MacOS and Windows, you must use the special URL `host.docker.internal` as described in the [Docker networking documentation](https://docs.docker.com/desktop/mac/networking/#use-cases-and-workarounds).

    This also applies to the `upstream.url` endpoint property in your ngrok config file. For example:

    ```yaml theme={null}
    endpoints:
      - name: example
        url: https://example.ngrok.app
        upstream:
          url: http://host.docker.internal:80
    ```
  </Tab>
</Tabs>

Note: the Docker version of ngrok follows the same convention as the agent, for example:

```bash theme={null}
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http 80                            # secure public URL for port 80 web server
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http --url baz.ngrok.dev 8080   # port 8080 available at baz.ngrok.dev
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http foo.dev:80                    # tunnel to host:port instead of localhost
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http https://localhost:5001        # expose a local https server running on port 5001
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest tcp 22                             # tunnel arbitrary TCP traffic to port 22
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest tls --url foo.com 443           # TLS traffic for foo.com to port 443
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest start foo bar baz                  # start tunnels from the configuration file
```

### Basic usage

The ngrok docker image wraps the ngrok agent executable. Read the documentation for the [ngrok agent CLI docs](/agent/cli/) for all commands.

#### Run an ngrok Agent pointed at localhost:80

```bash theme={null}
docker run -it -e NGROK_AUTHTOKEN=your_token ngrok/ngrok http host.docker.internal:80
```

### Choose a URL

If you don't choose a URL, ngrok will assign one for you.

```bash theme={null}
docker run -it -e NGROK_AUTHTOKEN=your_token ngrok/ngrok http host.docker.internal:80 --url https://your-url-here.ngrok.app
```

### Add a Traffic Policy

[Traffic Policy](/traffic-policy/) is a configuration language that offers you the flexibility to filter, match, manage, and orchestrate traffic to your endpoints.

```bash theme={null}
docker run -it -v $(pwd)/traffic-policy.yml:/etc/traffic-policy.yml ngrok/ngrok:alpine http host.docker.internal:80 --traffic-policy-file /etc/traffic-policy.yml
```

##### `traffic-policy.yml`

```yaml theme={null}
on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - user:password123
```

#### Run in the background

```bash theme={null}
docker run -d --restart unless-stopped -e NGROK_AUTHTOKEN=your_token --name ngrok-agent ngrok/ngrok http host.docker.internal:80
```

### Use a configuration file

Run the ngrok agent with the config file `./ngrok.yml` from the host machine:

```bash theme={null}
docker run -it -v $(pwd)/ngrok.yml:/etc/ngrok.yml -e NGROK_CONFIG=/etc/ngrok.yml ngrok/ngrok:alpine http host.docker.internal:80
```

#### Pull the ngrok container image

```bash theme={null}
docker pull ngrok/ngrok
```

## Traffic Inspection

#### Traffic Inspector

Use [Traffic Inspector](https://dashboard.ngrok.com/ac_aHNlbPD0YUEUrqWbr9xZQJUflCx/traffic-inspector) on your ngrok dashboard

#### Local web inspection on localhost:4040 (Legacy)

The agent serves this web interface on port 4040 so you'll need to publish it as well with `-p 4040:4040`

```bash theme={null}
docker run -it -p 4040:4040 ngrok/ngrok http host.docker.internal:80
```

If you are unable to view the web inspection interface typically available at `http://localhost:4040`, you may need to map your host port `4040` to port `4040` on the container, for example:

```bash theme={null}
docker run -p 4040:4040 -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http host.docker.internal:80
```