# Virtuoso Bridge

Virtuoso Bridge allows Virtuoso to access your local or private application, without the need of changes on the firewall or routing rules on your infrastructure. This enables seamless usage of Virtuoso on:

  • Internal environments behind firewall (e.g., staging and testing environments)
  • Applications with restricted access within your organization network (e.g. https://privateapp.intranet)
  • Local development environments (see Testing local applications for more details)

This is achieved using two components:

  1. Virtuoso Bridge Client - Establishes a secure connection (TLS-encrypted) to the Virtuoso Bridge Server which is then used as a secure tunnel to forward all requests made by Virtuoso Bots through that specific Virtuoso Bridge Client to your internal network.

  2. Virtuoso Bridge Server - Acts as proxy for all traffic coming from Virtuoso Bots and allows access to all network applications accessible by the machine where Virtuoso Bridge Client is deployed.

The following diagram illustrates this functionality, and the connections between the Virtuoso Bridge components, your internal application and Virtuoso Bots.

Bridge overview

The remaining of this section presents the following topics:

# Setup a Virtuoso Bridge

To set up a new Virtuoso Bridge:

  1. Obtain the Virtuoso Bridge client for your operative system (no installation is necessary):

  2. Launch it, providing the authentication parameters:


    • -e (--email) : User email to access Virtuoso
    • -p (--password) : User password to access Virtuoso

    If both token and email/password are provided, token will be used


# Linux
chmod +x bridge_client
./bridge_client --token 37d7ec5e-cf57-45a3-8715-7a5c3e8f4115

# MacOS
chmod +x bridge_client.app
./bridge_client.app --token 37d7ec5e-cf57-45a3-8715-7a5c3e8f4115

# Windows
bridge_client.exe --token 37d7ec5e-cf57-45a3-8715-7a5c3e8f4115

There are also some optional parameters:

  • -n (--name) : Identifier for the bridge (this will appear as your bridge name on Virtuoso). If not provided, the MAC Address of the default network adapter will be used.
  • -o (--out) : Specifies the full path of a log file to be used. If not provided, standard output will be used. Alternatively the value "none" can be used to disable logging completely.
  • -l (--log-level) : Specifies the log level using DEBUG, INFO, WARNING or ERROR (default).
  • --max-retry-time : Specifies the maximum time the client will retry connecting to Virtuoso on connection failure before exiting, in the form of <hours>h<minutes>m<seconds>s (ex: 34m, 1h30m) (default 5m)
Using the bridge on other Virtuoso environments

By default, the bridge client will connect to Virtuoso production environment. This can be overridden with the following options:

  • --staging : Use Virtuoso staging environment
  • --api [api endpoint url] : Target a custom Virtuoso environment API, e.g., https://custom-api.virtuoso.qa
  • -b (--bridge) [custom bridge server(s) address] : Use Virtuoso Bridge custom endpoint(s) separated by ';', in the format server:port[;server2:port]. This parameter is mandatory when using a custom api endpoint url

# Using a Virtuoso Bridge

To use a previously set Virtuoso Bridge, set it up on the Advanced Settings section of a Goal:

Goal Bridge setup

The drop down list will present the bridge id and name of the user that initiated it:

Goal Bridge setup detail

This list will be composed by all public bridges associated with an organization.

Connection capacity at the bridge client

With the bridge, the bandwidth available to Virtuoso will be limited by the capacity of the connection to the bridge server from the client, and from the client to the application under test.

By default, Virtuoso will not limit the number of concurrent sessions sharing the bridge. Bandwidth capacity through the bridge is limited by the capacity of the internet connection (and VPN if in use) of the host running the client, both to the bridge server and to the application under test.

If your goal has many journeys or the bridge client is running over an unstable or limited-bandwidth connection, this can lead to request timeouts which in turn cause journeys to fail part-way through or in some cases a blank screenshot on the first step.

When this happens, you can use the maximum parallelism setting on goals and plans to limit the maximum number of bots testing at the same time. If possible, avoid running the bridge client on machines that require a VPN to access the target application by running the client on a host within the network instead.

# Testing local applications

Due to Chrome browser limitations, it is not possible to direct requests to "localhost" or "" through Virtuoso Bridge. To overcome this, the configuration should be adjusted to access an alternative address / IP. To support this, on bridge client launch the alternative options available will be presented:

| For access to localhost applications, in Virtuoso please replace localhost by one of the following:
| myhostname
| Example:
| http://localhost:8080 -> http://myhostname:8080
| For more details please check documentation at:
| https://docs.virtuoso.qa/guide/advanced-topics/virtuoso-bridge/#setup-a-virtuoso-bridge

On the goal configuration url and any navigate test steps, localhost should be replaced by one of the presented options.

# Virtuoso Bridge proxy support

Depending on your network architecture or connectivity requirements, it might be needed to use Virtuoso bridge with one or two proxies:

Bridge proxy

If your application can only be accessed through a http proxy or if you require that all traffic targeting the application is directed through a http proxy, you can use the following parameter:

  • --application-http-proxy [http proxy], the proxy value should be provided in the form of <proxy_address>:<proxy_port> (e.g., This proxy must be a HTTP proxy.

On the other hand, your Virtuoso bridge might not be able to reach our Virtuoso servers directly, and it needs a proxy connection too. For these cases, you can use this parameter to configure where the bridge client should point to reach external networks:

  • --outbound-socks-proxy [socks proxy], the proxy value should be provided in the form of <proxy_address>:<proxy_port> (e.g., This proxy must be a SOCKS proxy to properly communicate with Virtuoso.

# Using OWASP® Zed Attack Proxy (ZAP) with Virtuoso Bridge

One of the use cases for Virtuoso bridge proxy support is to integrate with OWASP ZAP tool for security auditing your application via Virtuoso. This can be achieved by using ZAP proxy functionality, and setting up Virtuoso bridge to use it as application proxy (--application-http-proxy parameter).

To obtain the ZAP proxy info using the GUI, launch it and from the menu select Tools->Options:

ZAP Options

From the options window select Local Proxies to view or change the ZAP proxy info:

ZAP Proxy

This info is also shown on the ZAP window status bar:

ZAP Proxy Status Bar

If you are running ZAP in daemon mode, check for the log message with the proxy info:

[ZAP-daemon] INFO  org.zaproxy.zap.DaemonBootstrap - ZAP is now listening on localhost:8888

This is the value you should use while starting the Virtuoso Bridge to allow all traffic to be directed through ZAP. Using the information from the above example it should be:

bridge_client --token <TOKEN> -n zap_bridge --application-http-proxy localhost:8888

Then all tests executed within a Goal setup to use this bridge will be directed to ZAP and subject to analysis:

ZAP Events

When using ZAP the new HUD functionality should be disabled so ZAP does not change the website and affect the journeys/screenshots captured by Virtuoso. To do so, on the options screen select HUD and ensure that Show the HUD welcome screen when a browser is opened is unchecked:

ZAP Disable HUF

For more details on using ZAP see the official documentation

Last Updated: 7/14/2021, 7:07:52 AM