
## How the connection works {#overview}

A caller sends an HTTP request to the tunnel's public HTTPS address. Adal CLI calls the configured service from the computer where it runs and streams the service's HTTP response back to the caller. Request and response data can flow independently during the exchange, including when the local application responds before the caller finishes uploading.

For a runnable example, see the [quickstart](/en/docs/tunnels/quickstart).

## Tunnel settings {#settings}

| Setting | Behavior |
|---|---|
| **Name**, **Notes** | Identify the tunnel in the dashboard. Notes are optional and support up to 4,096 characters. |
| **Region** | Determines the public address and where HTTP data is kept. Choose it when creating the tunnel. The region and address are fixed afterward. |
| **Endpoint URL** | Base HTTP or HTTPS URL reachable from the CLI computer. Loopback and private addresses are allowed. Use a host and optional port and path. Leave out credentials, query and fragment. HTTPS certificates are verified. |
| **Enabled** | Opens the tunnel once CLI is connected and the configuration is ready. Disabling or deleting the tunnel closes the session and cancels active requests. |
| **Timeout (seconds)** | 1–120 seconds for the exchange, 30 by default. |
| **Concurrent requests** | 1–64 simultaneous exchanges per tunnel, 16 by default. Requests above the available capacity are rejected immediately. |
| **Save request**, **Save response** | Independent storage switches, both on by default. See [HTTP data and downloads](/en/docs/tunnels/http-data). |

With the Endpoint URL `http://127.0.0.1:3000/api`, a request to the public path `/orders?view=summary` is sent to `http://127.0.0.1:3000/api/orders?view=summary`. The destination host and HTTPS server name come from the Endpoint URL.

If the local service accepts `POST /api/orders`, test the same call through the tunnel. Replace the example host with the public address from the card.

```bash
curl -i 'https://TUNNEL_ADDRESS.se.adal.cloud/orders?view=summary' \
  -H 'Content-Type: application/json' --data '{"event":"demo"}'
```

```powershell
$body = @{ event = 'demo' } | ConvertTo-Json -Compress
Invoke-WebRequest -Uri 'https://TUNNEL_ADDRESS.se.adal.cloud/orders?view=summary' -Method Post -ContentType 'application/json' -Body $body
```

The caller receives the status, headers and body from the same request.

## CLI commands and token {#commands}

In [Tunnels](https://dashboard.adal.cloud/tunnels), open the tunnel card, select **CLI token**, and issue a token. Choose 30, 60 or 90 days, or a calendar expiration date in UTC. Save the secret when it is shown. Replacing or revoking the token ends its access. Restart CLI with the new token after replacement.

```bash
./adal-cli --token '<TUNNEL_TOKEN>'
./adal-cli --host wss://cli.adal.cloud --token '<TUNNEL_TOKEN>'
./adal-cli --help
```

```powershell
.\adal-cli.exe --token '<TUNNEL_TOKEN>'
.\adal-cli.exe --host wss://cli.adal.cloud --token '<TUNNEL_TOKEN>'
.\adal-cli.exe --help
```

The connection defaults to `wss://cli.adal.cloud`. The optional `--host` takes precedence over `ADAL_API_HOST`. Use a WSS origin without a path, query or credentials. The tunnel token selects the mode. A Channel token connects Inbound delivery.

## HTTP and traffic limits {#limits}

- Request and response bodies are each limited to 128 MiB. The regional HTTP handler limits request headers to 64 KiB and the request target to 16 KiB. An oversized body detected after streaming starts can interrupt the transfer.
- HTTP requests and responses can stream in both directions. WebSocket upgrades and HTTP `CONNECT` are unsupported. CLI returns the local HTTP status, including redirects and `4xx` or `5xx` responses. It does not follow redirects.
- Tunnel requests have no delivery queue, automatic HTTP retries or replay. On disconnect, active exchanges are cancelled. The client reconnects after temporary failures. After the tunnel is disabled and enabled again, start CLI manually.
- Admission requires a known, positive [traffic balance](/en/docs/common/traffic#tunnel). Usage is based on the body bytes actually received in both directions, regardless of storage switches.

## Logs and troubleshooting {#troubleshooting}

Check the terminal for CLI connection errors. Read the HTTP status and transfer outcome in the request journal. Keep the tunnel token private. Use the [journal](/en/docs/tunnels/history) to tell an Endpoint response from a response generated by the platform.

| Symptom | Check |
|---|---|
| CLI does not connect | Check the CLI version, tunnel token, expiration, tunnel state and access to `wss://cli.adal.cloud`. Run a fresh client after re-enabling a tunnel. |
| `404 tunnel_not_found` | Copy the full public URL from the card. Check the region and that the tunnel still exists. |
| `403 quota_exhausted` or `access_disabled` | Check balance and account access. |
| `503 tunnel_disabled`, `tunnel_not_ready`, or `quota_unavailable` | Check **Enabled**, refresh the connection state and confirm that CLI is connected. Check balance availability if the error names quota. |
| `503 concurrency_limit_exceeded` or `service_overloaded` | Check **Concurrent requests** and reduce simultaneous calls. |
| `502 endpoint_unavailable` | Call the Endpoint directly from the CLI computer. Confirm the service, port and TLS certificate. |
| `502 cli_unavailable` or `tunnel_transport_error` | Check that CLI is connected and inspect the transfer in the journal. |
| `400 invalid_request` | Check the HTTP request and its target. |
| `500 internal_error` | Note the time and request ID if available for troubleshooting. |
| `504 request_timeout` | Check application latency and **Timeout (seconds)**. A response that has already begun can end as an incomplete transfer. |
| `413`, `414`, `431`, `417`, or `501` | Check body size, target length, header size, the `Expect` header or use of `CONNECT` and upgrades, respectively. |

See [journal and statuses](/en/docs/tunnels/history) and [HTTP data and downloads](/en/docs/tunnels/http-data).
