Run probes from more than one location by attaching regional agents to your master. The master holds the schedule, fans jobs out per region, and aggregates results. Agents are stateless: they need only outbound HTTPS back to the master, no database, no Redis, no inbound ports. An agent runs fine on a small VPS or a home lab.
How it works#
The master schedules jobs. For each due monitor it looks up the regions it is bound to. With no regions attached, the job runs locally on the master (standard single-node behavior). With regions attached, the job is dispatched to the matching agents. Agents long-poll the master for work, run the probe locally, and POST the result back. Each agent only ever sees its own region's jobs, authorized by its own API key. Because agents talk to the master over outbound HTTPS only, they work through NAT, firewalls, and home routers without exposing anything inbound.
Add a region#
Prerequisite: the master must be reachable from the agent box. By default the master binds to 127.0.0.1, so either front it with public HTTPS (the docker-compose.tls.yml Caddy overlay, see API keys and deployment) or put the master and agents on the same private network (Tailscale or Wireguard).
1. Create the region on the master. Open Regions in the dashboard, enter a slug (lowercase and dashes, like us-east) and a label, and click Create region. The cleartext agent key is shown only once, so copy it.
2. Configure the agent box. Fetch the agent compose file and env template, then set three values:
OO_MASTER_URL=https://master.example.comOO_AGENT_KEY=oo_…OO_REGION_SLUG=us-east
OO_MASTER_URL=https://master.example.comOO_AGENT_KEY=oo_…OO_REGION_SLUG=us-east
Start it with docker compose -f docker-compose.agent.yml up -d and watch the logs for the first successful poll.
3. Bind monitors to the region from the + Add monitor dialog's "Run from" section.
Self-signed masters#
By default the agent validates the master's TLS certificate, so a self-signed master is rejected. Use a real certificate (Let's Encrypt via the Caddy overlay), install a private CA on the agent box, or tunnel the master and agents over Tailscale or Wireguard. As a last resort you can set OO_AGENT_TLS_INSECURE=1 on the agent, which disables certificate verification for the agent-to-master link only. It is not low risk: anyone on that network path could then read or tamper with the traffic. Reserve it for a home lab you control end to end, never the public internet. The agent logs a loud warning while it is on.