On-premise monitoring agents

Do I need an on-premise agent?

In short, if you'ure using Whoops.io to monitor websites or servers which are reachable publicly from the internet, then no, you do not need on-premise agents.

The primary purpose of on-premise agents is to allow you to monitor servers which are inside a private network you control, which are not exposed to the public internet

Read our on-premise agents announcement for more information.


  1. Install Docker:

    Our agent ships as a docker image, so if you aren't familiar with Docker already, you'll need a server somewhere on your network that has Docker installed and running.

  2. Get your API credentials:

    Log in to your Whoops account, select the workspace you want to monitor using your on-prem agent, and go to Settings. Scroll to the bottom of the page and make note of your Workspace ID, User ID, and API Token.

  3. Run the agent:

    This is a simple docker run command, passing your credentials/settings as environment variables.

    You'll need to set each of the following environment variables:

    • WHOOPS_PLATFORM_BASE_URI Always set to https://api.whoops.io
    • WHOOPS_USER_ID Your User ID
    • WHOOPS_WORKSPACE_ID Your Workspace ID *
    • WHOOPS_AGENT_NAME A custom name you define ( e.g. my-onprem-agent)

    Here's a full example:

    docker run \
       -e WHOOPS_PLATFORM_BASE_URI=https://api.whoops.io \
       -e WHOOPS_USER_ID=my-user-id \
       -e WHOOPS_PLATFORM_AUTH_TOKEN=my-api-token \
       -e WHOOPS_WORKSPACE_ID=my-workspace-id \
       -e WHOOPS_AGENT_NAME=my-onprem-agent \
       --network=host \

    *If you do not set a WHOOPS_WORKSPACE_ID then the on-prem agent will run uptime checks for checks across all workspaces you have access to. So if you have multiple workspaces, and want to run uptime checks on them all from the same on-prem agent, then do not set this env var.

    **If you do not set WHOOPS_ALLOW_PRIVATE_SUBNETS to true, then the on-prem agent will skip any checks it finds within any reserved IP address ranges.

  4. Setup your checks:

    Log in to the Whoops.io platform and configure your checks as normal. Our normal cloud agents will automatically recognise any checks which target internal/private addresses; our cloud agents will skip them, but your on-premise agent(s) will execute the check.

Running multiple on-prem agents

You can run multiple on-prem agents at once for the same account/worksapace. Just make sure each agent has a unique WHOOPS_AGENT_NAME set.


If you have any questions or problems setting up your on-prem agent, feel free to get in touch with us via our support page.