The `cloudflared tunnel run` command is used to start and manage Cloudflare Tunnels. A Cloudflare Tunnel securely connects your origin services (like web servers, SSH servers, or databases) to Cloudflare's edge, without exposing them directly to the public internet. This means no open inbound ports on your firewall.

Basic Concept

A `cloudflared` tunnel establishes outbound-only connections to Cloudflare's global network. When a request comes to your Cloudflare domain, Cloudflare forwards it through the tunnel to your `cloudflared` instance, which then proxies it to your local service.

Syntax

Or, for ad-hoc tunnels (which are deprecated in favor of named tunnels with configurations):

When running a named tunnel, `cloudflared` typically looks for a configuration file (`config.yml` by default, or specified with `--config`).

Key Options (for `run`)

* `[TUNNEL_NAME_OR_UUID]`: The name or UUID of the tunnel you wish to run. This tunnel must have been created previously using `cloudflared tunnel create`. If omitted, `cloudflared` might try to run a tunnel based on the configuration file.

* `--config FILE`: Specifies the path to the configuration file (e.g., `~/.cloudflared/config.yml`). This file defines which services `cloudflared` should expose through the tunnel.

* `--url URL`: (Primarily for ad-hoc, deprecated tunnels) Specifies the local URL (`http://localhost:8000`, `ssh://localhost:22`) to proxy to the internet.

* `--metrics ADDR`: Starts an HTTP server for Prometheus metrics collection on the specified address (e.g., `localhost:2006`).

* `--loglevel LEVEL`: Sets the logging level (e.g., `debug`, `info`, `warn`, `error`, `fatal`). Default is `info`.

* `--origincert PATH`: Path to the tunnel's origin certificate. Usually automatically handled.

* `--pidfile PATH`: Writes the process ID to the specified file.

* `--record-metrics PATH`: Records metrics to a file.

* `--transport-protocol PROTOCOL`: Sets the transport protocol for the tunnel (e.g., `http2`, `quic`).

Usage Examples

#### 1. Running a Named Tunnel with a Configuration File (Recommended)

This is the most common and recommended way to use `cloudflared tunnel run`. You first define your services in a `config.yml` file.

**Prerequisites:**

* You have created a tunnel: `cloudflared tunnel create my-web-tunnel`

* You have logged in: `cloudflared tunnel login`

* You have a `~/.cloudflared/config.yml` file or a custom config file.

**Example `~/.cloudflared/config.yml`:**

**Command to run:**

This command will start `cloudflared` using the `my-web-tunnel` tunnel, and it will pick up the ingress rules from the `config.yml` file, routing traffic for `myapp.example.com` to `localhost:8000` and `admin.example.com` to `localhost:8080`.

#### 2. Running an Ad-Hoc Tunnel (Legacy/Temporary Use, Less Recommended)

This method is largely deprecated in favor of named tunnels with configuration files, but it allows for quick testing of a single local service without prior tunnel creation or a config file.

After running this, `cloudflared` will provide you with a temporary public URL (e.g., `https://random-string.trycloudflare.com`). Any traffic to this URL will be forwarded to your `http://localhost:8000` service. This tunnel exists only as long as the `cloudflared` process is running.

#### 3. Running with Custom Configuration File and Logging

If your configuration file is not in the default location, or you want to specify a different log level:

This runs the tunnel named `my-production-tunnel` using the `/etc/cloudflared/production-tunnel.yml` configuration and outputs detailed debug logs.

#### 4. Running a Tunnel as a System Service

For production environments, you typically run `cloudflared` as a system service (e.g., `systemd` on Linux). `cloudflared` can generate service files for you:

This automates the execution of `cloudflared tunnel run` in the background, ensuring it restarts on boot and manages its lifecycle.

Explanations

* **Named Tunnels vs. Ad-Hoc:** Named tunnels are persistent, managed via the Cloudflare dashboard, and tied to a configuration file (`config.yml`). Ad-hoc tunnels are temporary, provide a random `trycloudflare.com` URL, and are primarily for quick local testing. **Always use named tunnels for production.**

* **Configuration File (`config.yml`):** This file is crucial for named tunnels. It defines the tunnel's UUID or name, the credentials file location, and the `ingress` rules. Ingress rules map hostnames (or paths) to local services, allowing you to expose multiple services through a single tunnel.

* **Credentials File:** When you `cloudflared tunnel create` and `cloudflared tunnel login`, `cloudflared` generates a credentials file (e.g., `~/.cloudflared/YOUR_TUNNEL_UUID.json`). This file contains the necessary authentication tokens for your `cloudflared` instance to connect to your specific tunnel on Cloudflare's network.

* **Security:** `cloudflared tunnel run` establishes an *outbound* connection to Cloudflare. This means your origin server does not need any open inbound ports, significantly reducing its attack surface and simplifying firewall rules. All traffic is encapsulated and proxied through Cloudflare's network.

* **High Availability:** You can run multiple instances of `cloudflared tunnel run` for the *same* tunnel name on different machines or in different data centers. Cloudflare's edge will automatically load balance traffic across these active tunnel instances, providing high availability and redundancy.

In summary, `cloudflared tunnel run` is the command that brings your Cloudflare Tunnel to life, connecting your private services to the Cloudflare network securely and efficiently.