Connect a satellite

A satellite is a small Checkstack agent you run somewhere the core server cannot reach directly: another region, another VPC, a customer site, an air-gapped network. Once a satellite is connected, you can pin specific health checks to run from it instead of from the core. For the full mental model, see Satellites.

This walkthrough mints a registration token in the UI, boots the satellite container with that token, and verifies the satellite comes online.

1. Open the Satellites page

From the user menu, open Satellites. The page lists every satellite registered on this instance, with name, region, status (online or offline), and version.

If this is your first satellite, the list shows an empty state explaining what satellites are and a Create satellite button.

2. Create the satellite record

1. Click Create satellite.
2. Fill in the dialog:
   • Name - human-readable, for example EU West Production.
   • Region - a descriptive identifier for the geographic location, for example eu-west-1, us-east-2, or datacenter-fra. This is free text, not an AWS region.
3. Click Create satellite.

Checkstack creates the satellite record and shows the credentials in a follow-up dialog.

3. Capture the credentials

The credentials dialog shows a Client ID (a UUID) and a Token (the bcrypt-hashed pairing token). Both are required by the satellite at startup.

Copy the token now. Checkstack only stores the hashed form; the plaintext value cannot be retrieved later. If you lose it, click the Reset token key icon next to the satellite in the list to mint a new one (this invalidates the old token).

The dialog also prints the three environment variables the satellite container needs:

CHECKSTACK_CORE_URL=<your-core-url>
CHECKSTACK_SATELLITE_CLIENT_ID=<the-client-id>
CHECKSTACK_SATELLITE_TOKEN=<the-token>

CHECKSTACK_CORE_URL is the public URL of your Checkstack core server (the same one you visit in the browser). The satellite opens a WebSocket against it.

4. Pull the satellite image

The satellite ships as a lean Docker image, built from Dockerfile.satellite in the repository. It bundles only healthcheck-* and collector-* plugins, not the full platform.

docker pull ghcr.io/enyineer/checkstack-satellite:latest

Tip

Pin the image tag to the same release as your core server in production. Running mismatched versions works in the short term but is not a supported configuration.

5. Boot the satellite container

Start the container with the three environment variables from step 3:

docker run -d \
  --name checkstack-satellite \
  --restart unless-stopped \
  -e CHECKSTACK_CORE_URL=https://checkstack.example.com \
  -e CHECKSTACK_SATELLITE_CLIENT_ID=<client-id> \
  -e CHECKSTACK_SATELLITE_TOKEN=<token> \
  ghcr.io/enyineer/checkstack-satellite:latest

The container fails fast if any of the three variables is missing. Tail the logs to confirm it connected:

docker logs -f checkstack-satellite

You should see lines like:

[satellite] Starting Checkstack Satellite v...
[satellite] Loading health check strategies...
[satellite] Core URL: https://checkstack.example.com
[satellite] Client ID: <client-id>
[satellite] Connected to core

If you see WebSocket close or authentication errors instead, double-check the URL, client ID, and token. The token must match the one the dialog showed in step 3 exactly.

6. Confirm the satellite is online

Back in Checkstack, refresh the Satellites page. The new satellite should now show:

• Status - online (green badge).
• Version - the satellite container version it reported at handshake.

The status updates in real time via WebSocket signals. If the satellite drops the connection, the badge flips to offline within a few seconds.

7. Assign a health check to the satellite

The point of the satellite is to run checks from its vantage point. Pin a check:

1. Open Health Checks and edit any check that supports satellite execution (network strategies like HTTP, TCP, ping, DNS all do).
2. In the Execution section, switch from Core to Satellite and pick your new satellite from the dropdown.
3. Save.

The next run executes on the satellite. The result returns through the WebSocket and lands in the check history alongside core-executed runs. The history detail page shows which satellite produced each run.

8. Manage the satellite over time

• Reset token - the key icon next to the satellite in the list mints a new token and invalidates the old one. Update the running container’s env var and restart.
• Delete - the trash icon removes the satellite. Any assignments pointing at it fall back to core execution.
• GitOps managed - if you manage satellites declaratively, see the kind: Satellite schema in GitOps kind reference. The bcrypt token is never expressed in YAML; you still use the Reset token button to mint one.

See also

• Satellites - the mental model.
• GitOps kind reference - declaring satellites in YAML.
• Set up your first health check - the prerequisite for pinning a check to a satellite.