Quickstart

This path brings up the RootPilot Agent with the demo environment: the full catalog answered from a fixture, without a single credential of yours, with a planted incident that always just happened.

It is the first thing to do on a new install. It validates the plumbing — the image runs in your environment, the certificate is valid, the tunnel is reachable — before you provision any credential. If something fails here, it would fail the same way in the real install, only with secrets in the mix.

What you need

• The image address and pull authorization, which RootPilot sends you.
• An identity for the Agent — on most installs that is a bootstrap token, which you mint yourself under Onboarding in the control-plane. If RootPilot handed you an already-issued certificate (runner.crt, runner.key, ca.pem), that works here just as well. See Identity and enrollment.
• The tunnel URL (RUNNER_TUNNEL_URL).
• Outbound HTTPS to the tunnel host. No inbound ports.

1. Pull the image

# AWS (ECR)
docker pull <rootpilot-account>.dkr.ecr.<region>.amazonaws.com/rootpilot-agent:<version>

# GCP (Artifact Registry)
docker pull <region>-docker.pkg.dev/<rootpilot-project>/rootpilot/rootpilot-agent:<version>

The image is multi-architecture: the same address serves amd64 and arm64.

The registry is private — if the pull fails with no basic auth credentials, you have not authenticated yet. Two commands, one per cloud, in The image › Authenticate before pulling.

2. Run in demo mode

With a bootstrap token — the path the Onboarding page hands you ready to run:

docker run --rm \
  -e RUNNER_TUNNEL_URL=wss://tunnel.rootpilot.sh:8443 \
  -e RUNNER_ENROLL_URL=https://app.rootpilot.sh \
  -e RUNNER_ATTESTATION_MODE=bootstrap-token \
  -e RUNNER_BOOTSTRAP_TOKEN=<the token you minted> \
  -e RUNNER_CONNECTORS=demo \
  <image-address>

With a provisioned certificate, if that is what you received: put the three PEMs in a directory and mount it at /certs — the entrypoint loads them for you, and neither RUNNER_ENROLL_URL nor the token is needed.

docker run --rm \
  -v "$PWD/certs:/certs:ro" \
  -e RUNNER_TUNNEL_URL=wss://tunnel.rootpilot.sh:8443 \
  -e RUNNER_CONNECTORS=demo \
  <image-address>

None of your credentials go into either one. demo answers from a fixture.

The token is single-use

It is good for one enrollment and expires in an hour. Running this command again means minting another — acceptable in a test, and not how you run it in production: see Identity and enrollment.

3. Confirm the boot

Logs are JSON, one line per event:

{"level":"info","message":"boot: liveness","context":"runner","instanceId":"..."}
{"level":"info","message":"enrolled","context":"runner","spiffeId":"spiffe://rootpilot/tenant/<you>/runner"}
{"level":"info","message":"boot: ready","context":"runner","instanceId":"..."}
{"level":"info","message":"hello accepted","context":"runner","sessionId":"..."}

With a provisioned certificate, the second line is using provisioned cert and carries a notAfter — the date it expires.

hello accepted is the line that matters: from there the Agent is connected and shows up in the control-plane Fleet view.

Check the tenant on the SPIFFE id line

spiffe://rootpilot/tenant/<slug>/runner says which organization this Agent joined. That is the check worth doing now, because a token minted in the wrong org comes up and connects — just in the wrong place.

And if you used a provisioned certificate: note the notAfter. It does not renew itself; when it expires, the Agent stops connecting. Write the date down — the subject is covered in Identity and enrollment.

If you see disconnected, reconnecting in a loop, the Agent is up and the tunnel is not: check the URL, egress, and certificate validity. See troubleshooting.

The three data modes

RUNNER_CONNECTORS decides where answers come from. Getting it wrong is the most common cause of “I installed it and the tools return garbage”.

Mode	Credentials	What it answers
synthetic	none	Image default. A seed of 3 operations whose shapes do not match the real connectors. Good for proving boot and handshake, not for exercising tools.
demo	none	The full catalog (~190 ops) from a fixture, time-shifted. This quickstart’s mode.
real	yours	The real APIs. This is the production mode.

synthetic is the default, and it is not a mock of the tools

If you omit RUNNER_CONNECTORS, you land on synthetic — and the Agent boots, connects, and works, answering fabricated data. It is the quietest failure in the install. To demo without credentials the mode is demo; for real, it is real.

Next step

• To install for real: Production deployment.
• To connect your sources: Connector modes and Connector credentials.