Skip to content
Docs
Arcus
Popular questions
↑↓ to navigate↵ to selectesc to close
Book a demo

Set up an Arcus tunnel

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 testUse
An app on the internetA cloud run configuration, with no tunnel
An app only your network can reach, on Testsigma’s labsA cloud run configuration with a tunnel
An app on your own machine, with your own browsers and devicesA Local Agent run configuration. See 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.

  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:

    PlatformFileBuilds
    macOS.zipApple silicon, Intel
    Windows.zipx64, Arm
    Linux.zipx64, Arm
    Debian, Ubuntu.debx64, Arm
    RHEL, Fedora.rpmx64, 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

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.

  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

The generated args.yaml looks like this:

key: "<API_KEY>"
tunnel-name: "<TUNNEL_NAME>"
verbose: false
delegate-ssl-validation: false
proxy: ""
SettingWhat it does
keyThe API key the client signs in with
tunnel-nameThe name the tunnel registers under. It must match the name you entered in Arcus
verboseWrites debug logs when true
delegate-ssl-validationAccepts certificates from an SSL inspection appliance on your network when true
proxyThe proxy the client connects through, when your network requires one

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

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

With args.yaml:

Terminal window
./ArcusTunnel

With flags:

Terminal window
./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

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.

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.

  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.

  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

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

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.

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

ProblemWhat to do
The tunnel isn’t runningWait for the client to print “Tunnel server is ready and connected!”
args.yaml isn’t usedKeep it beside ArcusTunnel. The client warns when it can’t read or parse the file
The name doesn’t matchStart the client with the same tunnel name you entered in Arcus
The key isn’t validGenerate a new one in API Keys
Tunnels aren’t in your planSee Usage and Credits
The tunnel limit is reachedAll the tunnels your plan allows are running. Delete one, or see Usage and Credits

A run goes to the internet instead of the tunnel

Section titled “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.

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.

Was this page helpful?