New announcements for Serverless, Network, RUM, and more from Dash! New announcements from Dash!

Run Synthetics tests from Private Locations

This feature is in beta. To enable Synthetics private locations for your account, use the corresponding sign-up form for the Datadog US site or for the Datadog EU site.


Private locations allow you to monitor internal-facing applications or any private URLs that aren’t accessible from the public internet. They can also be used to create a new custom Synthetics location.


The private location worker is shipped as a Docker container. By default, every second, your private location worker pulls your test configurations from Datadog’s servers using HTTPS, executes the test depending on the frequency defined in the configuration of the test, and returns the test results to Datadog’s servers.

Once you created a private location, configuring a Synthetics API or Browser test from a private location is completely identical to the one of Datadog managed locations.

Create a new private location

  1. Go in Synthetics -> Settings -> Private Locations and create a new private location:

  2. Fill out the Location Details and click Save and Generate to generate the configuration file associated with your private location on your worker.

    Private locations

    Note: The configuration file contains secrets for private location authentication, test configuration decryption, and test result encryption. Datadog does not store the secrets, so store them locally before leaving the Private Locations screen. You need to be able to reference these secrets again if you decide to add more workers, or to install workers on another host.

  3. Launch your worker as a standalone container using the Docker run command provided and the previously created configuration file:

    docker run --name synthetics-private-location-worker-<LOCATION_ID> \
               --rm -v $(pwd)/synthetics-private-location-worker-<LOCATION_ID>.json:/etc/synthetics-private-location-worker-<LOCATION_ID>.json datadog/synthetics-private-location-worker node /datadog-synthetics-agent/dist/worker.js \

    Note: To scale a private location, add or remove workers on your host.

  4. To pull test configurations and push test results, the private location worker needs access to one of the Datadog API endpoints:

    • For the Datadog US site:
    • For the Datadog EU site:

    Check if the endpoint corresponding to your Datadog Site is available from the host runing the worker:

    • For the Datadog US site: ping
    • For the Datadog EU site: ping
  5. If your private location reports correctly to Datadog you should see the corresponding pills displayed if the private location polled your endpoint less than 5 seconds before loading the settings or create test pages:

    • In your private locations list, in the Settings section:
    • In the form when creating a test, below the Private locations section:
  6. You should now be able to use your new private location as any other Datadog managed locations for your Synthetics API tests or Synthetics Browser tests.


The private location workers only pull data from Datadog servers. Datadog does not push data to the workers. The secret access key, used to authenticate your private location worker to the Datadog servers, uses an in-house protocol based on AWS Signature Version 4 protocol.

The test configurations are encrypted asymmetrically. The private key is used to decrypt the test configurations pulled by the workers from Datadog servers. The public key is used to encrypt the test results that are sent from the workers to Datadog’s servers.

Further Reading