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.
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.
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.
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_URIAlways set to
WHOOPS_USER_IDYour User ID
WHOOPS_PLATFORM_AUTH_TOKENYour API Token
WHOOPS_WORKSPACE_IDYour Workspace ID *
WHOOPS_AGENT_NAMEA custom name you define ( e.g.
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 \
-e WHOOPS_ALLOW_PRIVATE_SUBNETS=true \
*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.
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.
You can run multiple on-prem agents at once for the same account/worksapace. Just make sure each agent has a unique
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.