Pilot configuration reference

Applies to: Pilot manifest schema 1

Updated September 16, 2026

A pilot manifest describes the release, services, resource requirements and workloads for one evaluation. The package validates the document before using it. Keep a reviewed copy with the environment's runbook so that another operator can repeat the same configuration.

Document structure#

Field	Type and requirement	Meaning
`schema_version`	Integer; required, value `1`.	Configuration schema.
`name`	String; required.	Pilot identifier. Use 1–96 characters: a letter or digit first, followed by letters, digits, `_`, `.` or `-`.
`state_root`	Path string; default `./pilot-state`.	Directory for pilot state and result records. Relative paths resolve from the manifest's directory.
`release`	Optional object.	Application release to stage and activate.
`cgroups`	Array; default empty.	Named resource-control requirements.
`services`	Array; default empty.	Declared supervised services.
`workloads`	Array; default empty.	Named evaluation workloads.

The root must be a JSON object. Unknown fields, duplicate names and unresolved resource-group references are rejected. The maximum manifest size is 1 MiB. Use numeric JSON values for durations and limits where the supplied field requires them.

Commands and paths#

Commands are nonempty argument arrays, for example ["/bin/echo", "example"]. A shell command string is invalid. Pipes and redirection are not implicitly interpreted. Supply an explicit working directory when the program needs one.

Supported path substitutions are ${PILOT_ROOT} and ${RELEASE}. The latter requires an active release. Unknown substitutions produce an error. In an application command, ${RELEASE} identifies the active application package; it does not refer to Kestowv's source.

Application release#

Field	Meaning
`version`	Required release name, using the pilot-name character rules.
`source`	Required path to the prepared application package.
`manifest_sha256`	Optional expected manifest digest, expressed as 64 hexadecimal characters.
`health.command`	Argument array for the release acceptance check.
`health.timeout`	Positive duration in seconds; default `30`.
`health.poll_interval`	Positive delay between checks in seconds; default `1`.

Use a new version name when application contents change. The package rejects a different payload under an existing version name. A release health command should inspect a condition relevant to the application becoming usable; a process existing is often insufficient.

Services#

Field	Default or requirement
`name`, `command`	Required service name and argument array.
`cwd`	Optional working-directory path.
`env`	Optional object of nonsecret environment values.
`secret_env`	Optional map of environment names to protected file references.
`cgroup`	Optional name declared in `cgroups`.
`restart`	`on_failure`; also accepts `never` or `always`.
`max_restarts`	`5`; nonnegative restart budget.
`restart_window`	`60` seconds; positive budget window.
`backoff.initial`, `backoff.max`	`1` and `30` seconds; nonnegative retry delays.
`stop_timeout`	`10` seconds; nonnegative stop allowance.
`autostart`	`true`; whether the service should start when provisioned.
`out`, `err`	Optional output-file paths.
`health.command`	Optional service-check argument array.
`health.interval`, `health.timeout`, `health.failures`	`10` seconds, `3` seconds and `3` failed checks. Timeout and failure count must be positive; interval may be zero.

For example, an application supplied in the active release could be configured as follows. The executable and health command must actually exist in that application package; these names are placeholders.

{
  "name": "example-service",
  "command": ["${RELEASE}/bin/example-service"],
  "restart": "on_failure",
  "max_restarts": 3,
  "restart_window": 60,
  "health": {
    "command": ["${RELEASE}/bin/example-health"],
    "interval": 10,
    "timeout": 3,
    "failures": 3
  }
}

Credentials#

Use secret_env for secrets. Each value refers to a regular file readable by the service account, with no group or world access and no symbolic link. Do not put passwords, API keys or tokens into env or command arguments.

{
  "secret_env": {
    "EXAMPLE_API_TOKEN": { "file": "/path/to/protected/token-file" }
  }
}

The example is a service fragment. Provision the actual file through your environment's credential process before validation. A reference to a missing or improperly protected file fails validation.

Resource requirements#

A resource-group entry has name, controllers, limits and required. Supported controller names are cpu, memory, io and pids. required defaults to true. The host must support and delegate the declared controls; doctor reports readiness.

Choose limits for the agreed workload and the host's documented control interface. Do not change a required group to optional merely to pass a readiness check. An evaluation that depends on resource enforcement needs that enforcement on the actual target host.

Workloads#

Each workload requires a unique name and a kind: single, ab or soak. A run uses command, optional env and cwd, and a positive timeout defaulting to 60 seconds. Comparative workloads provide baseline and candidate run objects, iterations (default 1), warmup (default 0) and agreed thresholds. Soaks add duration and interval in seconds; both default to zero, so set a meaningful duration for a sustained evaluation.

Timed faults are optional entries with after and signal. They deliberately interrupt test work. Use them only in the isolated workload and maintenance scope defined by the evaluation plan. See Workload evaluations before interpreting any performance or recovery result.