# Set up an Arcus tunnel

> Run cloud tests against an app on localhost, on a private network, or behind a firewall, through a tunnel client on a machine that can reach it.

An **Arcus tunnel** lets tests on Testsigma's cloud labs reach an app that only your network can reach: a build on `localhost`, a staging site on a private network, or anything behind a firewall. You run a small client, **ArcusTunnel**, on a machine that can reach the app. The client opens an outbound connection to Arcus, so you don't open any inbound port.

Tunnels are set up in **Settings** > **Tunnels**, under **Execution**, and chosen in a run configuration.

| You want to test | Use |
|---|---|
| An app on the internet | A cloud run configuration, with no tunnel |
| An app only your network can reach, on Testsigma's labs | A cloud run configuration with a tunnel |
| An app on your own machine, with your own browsers and devices | A **Local Agent** run configuration. See [Arcus Agent](https://testsigma.com/docs/arcus/v2/get-started/installation/arcus-agent/) |

A tunnel has no effect on a **Local Agent** run, because that machine is already inside your network. Tunnels also don't work with a lab you connected yourself; they run on Testsigma's labs only.

Your plan sets whether you can use tunnels and how many can run at once. See [Usage and limits](https://testsigma.com/docs/arcus/v2/settings/organization/usage-and-limits/).

## Download the client

1. In the left navigation, open **Settings**, then click **Tunnels**.

2. Under **Download client**, click **Download client**. Arcus offers the build for the computer you're on. For another platform, click **All downloads** and pick one:

   | Platform | File | Builds |
   |---|---|---|
   | macOS | `.zip` | Apple silicon, Intel |
   | Windows | `.zip` | x64, Arm |
   | Linux | `.zip` | x64, Arm |
   | Debian, Ubuntu | `.deb` | x64, Arm |
   | RHEL, Fedora | `.rpm` | x64, Arm |

3. Copy the file to a machine that can reach the app you want to test, and extract or install it there.

The `.zip` holds the `ArcusTunnel` client with an `args.yaml` file beside it. The `.deb` and `.rpm` packages install the client as a service that reads `args.yaml` from its folder in `/etc`.

![The Tunnels page with All downloads open, and the client builds for each platform outlined](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/arcus_tunnel/tunnel_downloads.webp)

## Configure the client

The client needs an API key and a tunnel name.

1. Under **Configure tunnel**, enter an **API key**. To create one, click **API Keys**. See [API keys](https://testsigma.com/docs/arcus/v2/settings/api-keys/).

2. Enter a **Tunnel name**, using lowercase letters, digits, and hyphens. This is the name you pick in run configurations.

3. Choose how the client reads them:
   - **args.yaml (recommended)**: click **Download args.yaml** and replace the `args.yaml` beside the client with it, or click **Copy** and paste the contents into that file. The key stays out of your shell history.
   - **Command line**: nothing to save. The start command passes the key and the name as flags. The key ends up in your shell history.

   ![Configure tunnel, with the API key and Tunnel name fields outlined, and the generated args.yaml with Copy and Download args.yaml outlined](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/arcus_tunnel/tunnel_configure.webp)

The generated `args.yaml` looks like this:

```yaml
key: "<API_KEY>"
tunnel-name: "<TUNNEL_NAME>"
verbose: false
delegate-ssl-validation: false
proxy: ""
```

| Setting | What it does |
|---|---|
| `key` | The API key the client signs in with |
| `tunnel-name` | The name the tunnel registers under. It must match the name you entered in Arcus |
| `verbose` | Writes debug logs when `true` |
| `delegate-ssl-validation` | Accepts certificates from an SSL inspection appliance on your network when `true` |
| `proxy` | The proxy the client connects through, when your network requires one |

A flag on the command line wins over the same setting in `args.yaml`.

## Start the client

From the client's folder, run the command Arcus shows under **Start the client**.

With `args.yaml`:

```bash
./ArcusTunnel
```

With flags:

```bash
./ArcusTunnel --key "<API_KEY>" --tunnel-name "<TUNNEL_NAME>"
```

The tunnel is up once the client prints "Tunnel server is ready and connected!". Keep the client running while tests use the tunnel.

![Start the client with the ./ArcusTunnel command outlined, and Verify connection with Check connection outlined](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/arcus_tunnel/tunnel_start_verify.webp)

To share the tunnel, start the client on more machines with the same `args.yaml`, or the same command. They all join one tunnel.

On Windows, the client is `ArcusTunnel.exe`.

## Check the connection

Under **Verify connection**, click **Check connection**. The tunnel shows as **Running** once a client has registered it.

A tunnel is created the first time a client starts with its name, and stops when its last client disconnects. The Tunnels page lists each tunnel with its **Name**, **Status**, **Port**, number of **Clients**, client **Version**, **Last change**, and **Last error**. Click a tunnel to open its details. A tunnel's **Status** is **Starting**, **Running**, **Stopping**, **Stopped**, or **Failed**. The filters above the list show each status that has tunnels, with its count.

### Delete a tunnel

1. On the Tunnels page, click the tunnel.

2. Under **Delete tunnel**, click **Delete tunnel**.

3. In the confirmation dialog, click **Delete**.

Deleting stops the tunnel, disconnects its clients, and frees its slot on your plan. Tests and API requests that used it then go directly over the public internet. To create it again, start a client with the same name.

You can't delete a tunnel that a run configuration uses, or one that is still **Starting**. Remove it from the run configuration first.

## Use a tunnel in a run configuration

1. Open **Test Runs**, click **Run Configs**, then click **New Run Config**, or open an existing configuration.

2. Under **Where to run**, select **Cloud**.

3. Under **Tunnel**, open **Send runs through** and select the tunnel. **None** sends runs straight to the internet.

   ![The Run Configuration panel with the Tunnel section and Send runs through outlined](https://s3.amazonaws.com/static-docs.testsigma.com/arcus/arcus_tunnel/run_config_tunnel.webp)

4. Click **Save**.

Browser and mobile sessions in a run that uses this configuration go through the tunnel, and so do its API steps. An API step that names its own tunnel uses that one instead. You can also pick a tunnel for **Send** in an API request.

Arcus refuses to start a run if its tunnel isn't running, so start the client before the run.

If no tunnel exists yet, the list reads "No tunnel yet." with a link to **Settings**. With **Local Agent** selected, the section reads "A Local machine already runs inside your network, so a tunnel has no effect there."

### Header rules for web runs

For a web configuration with a tunnel, **Header rules** add headers to the browser's requests to the hosts you match. Header values are encrypted and never shown again, and saving replaces every rule.

1. Under **Header rules**, click **Add rule**.

2. In the field that shows `api.internal`, enter the host: a domain such as `api.internal`, `*.internal` for the domain and its subdomains, or `*`.

3. Optionally, in the field that shows **All paths**, enter a path such as `/v1/orders`, `/v1/**`, or `**/health`.

4. In the field that shows `X-Auth-Token`, enter the header name. Enter its value in the field beside it.

5. Click **Save**.

Every rule needs a host, a header name, and a value. To delete a rule before saving, click its remove icon.

Once rules are saved, the section reads "Header rules are saved." Click **Replace** to enter a new set, or **Remove** to delete them when you save. To undo a removal before saving, click **Keep them**.

With header rules, the browser accepts the tunnel's certificate. This also hides certificate errors in your app during these runs.

## Troubleshooting

The **Troubleshoot** list on the Tunnels page covers the common causes:

| Problem | What to do |
|---|---|
| The tunnel isn't running | Wait for the client to print "Tunnel server is ready and connected!" |
| `args.yaml` isn't used | Keep it beside `ArcusTunnel`. The client warns when it can't read or parse the file |
| The name doesn't match | Start the client with the same tunnel name you entered in Arcus |
| The key isn't valid | Generate a new one in **API Keys** |
| Tunnels aren't in your plan | See **Usage and Credits** |
| The tunnel limit is reached | All the tunnels your plan allows are running. Delete one, or see **Usage and Credits** |

### A run goes to the internet instead of the tunnel

The run configuration's **Send runs through** is set to **None**. Select the tunnel and save.

### A run is refused when it starts

The run configuration's tunnel isn't running. Start the client on a machine that can reach the app, wait for "Tunnel server is ready and connected!", then start the run again.
