Terms and FAQ

Core terms

Control plane

The Web, API, api-worker, PostgreSQL, MinIO, Nginx, and Monitoring services that store configuration and coordinate work. The control plane does not generate load itself.

Runtime

The versioned Linux execution bundle installed on a Load Node. Source full-stack startup builds or reuses the native-architecture Runtime. A tagged release downloads and validates the selected prebuilt Runtime assets.

Load Node

A Linux machine that runs the independent SurgePilot Runner and load-testing engine. A node must be registered, initialized, reachable, and Idle before a Run can select it.

Env Group

A reusable set of environment variables. Plain values can be read after save. Secret values are accepted through the signed-in UI and returned only as masked metadata; they cannot be revealed through the product.

Scenario

A reusable ordered flow of HTTP Steps, with request details and structured global configuration. A Scenario describes what to call, not how much load to generate.

Test Plan

A saved execution definition that combines Scenarios, an optional Env Group, resource selection, per-Scenario load settings, and optional SLA rules.

Debug Run and Standard Run

A Debug Run is a focused, single-node validation path. A Standard Run uses the Test Plan's resource and load configuration, evaluates its SLA rules, and can send enabled metrics to Monitoring.

Run and Run Report

A Run is one execution of a saved source revision. Its Run Report shows the terminal verdict, metrics, immutable snapshot, diagnostics, artifacts, and per-node state.

Preview

“Preview” has two separate meanings:

• Source preview is make start-preview, a control-plane startup mode that does not promise Runtime, Load Node, or Run readiness.
• Generated YAML Preview is a read-only Test Plan view of the configuration generated by the API for the latest saved revision. It does not start a Run.

SurgePilot does not expose a separate Scenario execution preview.

Frequently asked questions

Which startup mode should I use?

Use surgepilot up for a tagged self-hosted release. Use make start-full-stack when developing from source or validating the complete source execution path. Use make start-preview only for login, UI, control-plane, or Monitoring review without execution readiness.

Do I need to create or edit .env before startup?

No for ordinary interactive startup. surgepilot up, make start-full-stack, and make start-preview create secure deployment state when .env is missing. Release first-run asks for the LAN host and ports; source startup uses its source-specific defaults. Existing .env files are authoritative and are not automatically overwritten or repaired. See Deployment Configuration before making a manual change.

Why does Setup Status say not_configured in source preview?

Preview intentionally skips Runtime preparation and disables the Demo Load Node. not_configured is therefore expected for the Runtime check. Start the source full stack when you need Load Node initialization or Run execution.

Why can I design assets but not start a Run?

Env Groups, Scenarios, and Test Plans can be created without an execution resource. A Run also needs a saved, runnable Test Plan and a matching initialized Load Node that is currently Idle.

Does the source full stack automatically register the Demo Load Node?

No. It starts the Demo SSH container and prepares its credentials, but an Admin must register it, verify its host key, and initialize it through Load Nodes.

Does a tagged release include a Demo Load Node?

The release bundle contains an optional Demo profile, but ordinary release startup keeps it disabled. Register an external Linux Load Node for execution.

Can a Load Node use localhost to reach SurgePilot?

Not when the node runs on another machine or in another container. localhost then points to that node itself. Configure node-facing API and InfluxDB URLs with an address reachable from the Load Node. The release first-run prompt asks for this address explicitly.

Does down delete my configuration or results?

No. surgepilot down, make stop-full-stack, and make stop-preview stop their Compose services without deleting the deployment .env or named volumes.

Is direct-LAN HTTP suitable for the public internet?

No. The interactive tagged-release setup configures trusted-LAN HTTP. Public exposure requires an operator-managed HTTPS reverse proxy, final node-facing origins, a secure session cookie, firewall policy, and normal production operations controls.

Can SurgePilot test macOS Load Nodes?

No. macOS can host the containerized control plane through Docker Desktop, but Load Nodes and their Runtime are Linux-only.