Quickstart

This path brings the runner up on your machine with the demo environment: the whole catalog answered from a fixture, without one cloud credential, with a planted incident that always just happened.

What this repository does on its own, and what it doesn’t

The runner is the “hands” half. It boots, proves identity, and opens the tunnel, but the thing that requests operations is the control-plane. With no control-plane listening on the other side, the runner boots and sits in a reconnect loop, which is correct behavior and not an error. Use this quickstart to validate build, boot, and handshake; to see tools answering, point it at your organization’s control-plane.

1. Clone and build

git clone https://github.com/sunnysystems/rootpilot-edge.git
cd rootpilot-edge
npm install
npm run build

2. Run the tests

Worth doing before anything else: it’s what proves the tree is sound on your machine.

npm test

3. Mint development certificates

The real identity path is enrollment. For local development there’s a shortcut: a dev CA that signs the tunnel certificate and the runner’s client certificate, with the SPIFFE SAN inside.

npm run dev:certs

This writes to dev-certs/, which is gitignored and valid for 30 days.

4. Bring the runner up

RUNNER_CONNECTORS=demo npm run dev:runner

A successful boot looks like this:

boot: liveness {instanceId: "runner-dev-1"}
using provisioned cert (dev/test shortcut) {spiffeId: "spiffe://rootpilot/tenant/demo/runner"}
boot: ready {instanceId: "runner-dev-1"}

If you see 1006 → exited 0 → restart cycling, the runner is up and the tunnel isn’t. See the note above and troubleshooting.

The three data modes

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

Mode	Credentials	What it answers
synthetic	none	Default. A 3-operation seed whose shapes do not match the real connectors. Proves boot and handshake, not tool behavior.
demo	none	The whole catalog (~190 ops) from a fixture, time-shifted. This is the mode for demos and the consistency CI.
real	yours	The actual APIs.

synthetic is not a mock of the tools

It is the default, and it is the source of errors like entries.map is not a function or “op not implemented”. If you want to see tools working without credentials, the mode is demo, not synthetic.

Next

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