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

# Agent Packaging and Distribution

> Learn about the ways the ngrok agent is packaged and distributed, including standalone binaries, package managers, Docker, and Kubernetes.

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>;
};

The ngrok agent is a standalone native executable with zero runtime dependencies.
It runs on all major operating systems and architectures, and is distributed through multiple channels to fit your deployment environment.

## Installing the ngrok agent

The ngrok agent is available on many platforms and through many popular package managers.
Visit the [ngrok download page](https://download.ngrok.com) for specific installation instructions based on your setup.

### Standalone binary

The ngrok agent is available as a standalone binary with no runtime dependencies.
Download it directly from the [ngrok download page](https://download.ngrok.com).

The agent supports the following platforms:

| OS      | Supported architectures                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------- |
| Windows | 64-bit, 32-bit (`x86-64`, `x86`)                                                                     |
| macOS   | Intel, Apple Silicon (`x86-64`, `arm64`)                                                             |
| Linux   | `x86-64`, `x86`, `arm`, `arm64`, `mips`, `mips64`, `mips64le`, `mipsle`, `ppc64`, `ppc64le`, `s390x` |
| FreeBSD | `x86-64`, `x86`, `arm`                                                                               |

The agent can update itself with the [`ngrok update`](/agent/cli/#ngrok-update) command, even if you didn't install it with a package manager.

## Docker

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

For more details, see the [Using ngrok with Docker](/using-ngrok-with/docker) documentation.

### Docker Desktop extension

The ngrok Docker Desktop Extension lets you forward traffic from internet-accessible endpoint URLs to your local Docker containers directly from the Docker Desktop UI.

[Install the ngrok Docker Desktop Extension](https://open.docker.com/extensions/marketplace?extensionId=ngrok/ngrok-docker-extension) to get started.

For more details, see the [Docker Desktop](/using-ngrok-with/docker/desktop) documentation.

## Kubernetes

The ngrok Kubernetes Operator lets you manage ngrok resources natively from within your Kubernetes cluster using Helm.

Install the Operator with Helm:

```bash theme={null}
helm install ngrok-operator ngrok/ngrok-operator \
  --namespace ngrok-operator \
  --create-namespace \
  --set credentials.apiKey=$NGROK_API_KEY \
  --set credentials.authtoken=$NGROK_AUTHTOKEN
```

For more details, see the [Kubernetes Operator](/k8s/) documentation.