API Monitoring & Testing: On-premises Agent

The Runscope Radar Agent bridges Runscope to private APIs not available over the public internet. By running the agent within your infrastructure, Runscope API monitors and tests can run against endpoints that are otherwise inaccessible to the cloud agents. The agent is particularly useful if you're looking to test or monitor an API in the following situations:

  • Monitoring private or internal APIs that reside behind a firewall.
  • Testing APIs on localhost or in a private staging environment.
  • Accessing APIs that require a fixed client IP address (IP whitelisting).

Use of the agent requires a trial or paid subscription.

How it Works

Monitoring and testing private APIs with Runscope uses a hybrid on-premises approach. The agent runs on a host within your infrastructure but test data is managed and stored in the Runscope cloud. Using the Runscope dashboard, you have a single interface for defining tests, viewing results, configuring notifications and enabling 3rd-party integrations.

All communication from the agent to the Runscope cloud is made over outbound requests to the Runscope API via HTTPS on port 443. The agent requests work to be processed and sends back results over a TLS-encrypted connection and is not externally addressable.

How Runscope Radar Agent works

Downloading and Running the Agent

Select an operating system to download the agent:


Running the Agent

After downloading the agent, extract the executable from the .zip file and run it from your command line:

Linux and OS X

$ ./runscope-radar


C:\> runscope-radar.exe

You will be prompted to sign in to your Runscope account and select a team. Once authenticated, you can save a configuration file to be used for subsequent runs of the agent (without having to sign in). To launch the agent with a specific configuration file, use the -f command line option. This is the recommended way to start the agent.

Linux and OS X

$ ./runscope-radar -f radar.conf


C:\> runscope-radar.exe -f radar.conf

To generate a new configuration file, launch the agent without any command line options specified.


For SAML enabled accounts that do not have a username/password, you can run the agent for the first time by using the --token flag. You can get a token by going to your account's Applications page, creating a new application, and copying the Personal Access Token found at the bottom of the page. Then run the agent with:

Linux and OS X

$ ./runscope-radar --token=your_personal_access_token


C:\> runscope-radar.exe --token=your_personal_access_token

With the agent running, you're now ready to use it for your tests.

Using the Agent for Test Runs

After downloading and launching the agent, head over to the API test editor for the test you'd like to use the agent for. If everything is working correctly, the agent will appear as an option in the Locations section of the environment settings:

If you're testing an API across multiple realms (e.g. local, staging, prod), you may want to selectively enable the agent per-environment. The agent can also be enabled in a shared environment used across tests within a single bucket.

Command Line Flags / Configuration File Reference

You can specify the following parameters in your configuration file, or on the command line, when executing the agent. The configuration file will override the same parameters used in the command line.

--agent-id string Agent UUID.
--api-host string API host base URL.
--cafile string CA certificate file.
-f, --configfile string Start the agent with the configuration contained within the specified configuration file.
--debug Enable debugging web server.
--disconnect-timeout string Disconnect timeout. Default: "5".
-h, --help Show all available flags. Only works on the cli.
--ignore-env-proxy Ignore HTTP_PROXY and HTTPS_PROXY environment variables. Requests to api.runscope.com will still use the proxy.
-l, --logfile string Write logfile to an external file.
--name string The name of the agent to be displayed in the Runscope UI Locations menu.
--pidfile string Pidfile.
--team-id string Team UUID.
--threads integer Number of worker threads. Default: 10.
--timeout integer Connection idle timeout. Default: 20.
-t, --token string Runscope Auth Token.
-v, --verbose Log more information.
--verify-ssl boolean Verify SSL.
--version Get version number. Only works on the cli.
--web-host string Web host base url. Default: https://www.runscope.com.


Running the agent in verbose mode, and ignoring env proxy variables:

$ ./runscope-radar -f radar.conf -v --ignore-env-proxy

Configuration file with increased threads value to support a higher amount of requests, and ignoring environment proxy variables:



If you run into any issues while setting up or running the agent, such as difficulty connecting to api.runscope.com, or intermittent test errors, check out the following troubleshooting articles:

Need help running or configuring the Runscope Radar Agent in your infrastructure? Contact Support.

Next: Build/Deployment Integration →

Need help? We have you covered.

View the docs or contact our support team and we'll get back to you as soon as we're able to respond.