Private Locations

A private location runs the Yorker check runner on your own infrastructure instead of Yorker's hosted fleet. Use it to monitor internal services, staging environments, or anything behind a VPN -- from inside your own network. The same monitors, alerting, and dashboards work identically; the only difference is where the agent executes.

Private location runs are billed at 50% of hosted runs because you provide the compute.

Prerequisites

• A Yorker plan that includes private locations (free tier: 0; paid: up to 2; enterprise: unlimited)
• Docker installed on the target machine
• Outbound HTTPS access from the agent machine to app.yorkermonitoring.com:443 -- no inbound connections are required

Step 1: Create a Location

To create a location via the CLI, provide a unique slug (--name) and a human-readable label (--display-name):

yorker locations create --name hq-data-center --display-name "HQ Data Center"

The CLI also auto-generates a runner key. Use the key and location ID from the output when continuing with Step 3 below.

To create a location via the dashboard: go to Settings > Locations and click Add Location.

Both paths return a location ID in the form loc_.... Save it -- you will need it in the next step.

Step 2: Generate a Runner Key

Runner keys authenticate the agent to the control plane. Each key is shown only once.

To generate a key via the CLI:

yorker locations keys create <location-id>

To generate a key via the dashboard: expand the location row, enter a key name, and click Create Key.

Copy the key immediately -- it cannot be retrieved after the page is closed.

Step 3: Deploy the Agent

The repository includes a reference Docker Compose configuration at docker/docker-compose.private-agent.yml and an environment template at docker/private-agent.env.example. The template pre-fills RUNNER_MODE, CONTROL_PLANE_URL, and LOCATION_TYPE with their required values. You only need to supply the four values specific to your deployment:

# Copy the reference environment file
cp docker/private-agent.env.example docker/.env

Open docker/.env and fill in:

RUNNER_API_KEY=rk_...          # The runner key from Step 2
LOCATION_ID=loc_...            # The location ID from Step 1
TEAM_ID=team_...               # Included in the `yorker locations create` CLI output
LOCATION_NAME=HQ Data Center   # Human-readable label for logs and telemetry

Then start the agent:

docker compose -f docker/docker-compose.private-agent.yml up -d

Choosing an image

Two runner Dockerfiles are available:

The default Compose file builds the heavy image. To switch to the lighter image, comment out the yorker-agent service in the Compose file and uncomment yorker-agent-light.

Step 4: Verify Health

After the agent starts, it begins polling the control plane. To verify it is connected:

• Dashboard: the location's status badge turns green (Active) in Settings > Locations.
• CLI: run yorker locations list and check the status column.

Health states are derived from the time since the last successful poll:

If the agent does not appear Active within a few minutes, see Troubleshooting below.

Step 5: Assign the Location to a Monitor

Monitors only execute in the locations they are assigned to. A monitor can be assigned to any mix of hosted and private locations.

To assign via the dashboard: edit a monitor and open the location picker. Your private location appears under the Private group with its current health badge.

To assign via yorker.config.yaml, add the location ID to the monitor's locations array:

monitors:
  - name: Internal API
    type: http
    url: https://api.internal.example.com/health
    locations:
      - loc_us_east          # hosted location
      - loc_abcdef123456     # your private location

Deploy the config to apply:

yorker deploy

Network Requirements

The agent only needs outbound connectivity -- no inbound connections are required and no firewall rules need to be opened toward Yorker.

There is no VPN tunnel from the agent to Yorker's infrastructure. All communication is initiated by the agent over standard HTTPS.

Troubleshooting