Courier Runner

Courier Runner is the job execution agent for Chef 360 Platform. Whether a job is dispatched from the central platform or run locally for testing, Courier Runner is the component that interprets each step, runs the required commands, and reports the results.

What is Courier Runner

Courier Runner receives job instructions, coordinates with skill interpreters to run commands on the local node, tracks execution progress, and records output reports and execution artifacts. It works with skill interpreters—such as the Shell, Chef Infra Client, InSpec, Ansible, and Restart interpreters—to execute the individual steps in a job; see Skill interpreters for the full list and command syntax.

Courier Runner always runs in one of three modes, depending on whether it’s connected to the central platform. See Comparison for how the modes differ.

Standard mode

Courier Runner runs as a continuous service or daemon. It connects to a message queue, listens for jobs dispatched from the central Chef 360 Platform, executes each incoming job, and streams reports back to the platform API.

Zero mode

Zero mode lets you execute a Courier job locally on a node without connecting to a message queue or the central Chef 360 Platform. Courier Runner reads a job template from a local file or standard input, executes each step using local skill interpreters, and writes detailed execution reports and evidence files to the local filesystem. For the job template format and output file layout, see the reference; for the commands to run a job, see Run and validate Courier jobs locally.

Dry-run mode

Dry-run mode is a validation sub-mode of zero mode (--zero --dry-run). It parses and validates a job template against the local system—checking template syntax, interpreter availability, condition expressions, and cross-step data dependencies—without executing commands or saving database records. For the full list of checks and example output, see the reference.

Interpreter discovery

When executing a step, Courier Runner discovers the required interpreter using the following resolution order:

Configuration file: Courier Runner checks the interpreters list in the configuration file (~/.courier/config.yaml). If a matching interpreter entry contains an explicit path, Courier Runner uses that binary path.
Habitat package repository: If no explicit path is defined, Courier Runner queries the local Habitat installation for the specified package name.

Note

Each interpreter required by your job steps must be installed on the node or configured with an explicit binary path before running jobs.

Use cases

Local job testing and development: Test shell commands, script execution, and interpreter behavior on your own machine before scheduling jobs across production nodes.
CI/CD pipelines: Run automated tests and configuration tasks, or validate job templates before they’re submitted to the Courier scheduler, directly within continuous integration runners.
Air-gapped and isolated environments: Execute structured automation workflows—including InSpec compliance scans—on systems that don’t have network connectivity to the central platform.
Incident troubleshooting: Reproduce and validate job execution behavior locally instead of triggering live remote jobs against production or staging.

Comparison

Mode	Requires platform connection	Executes commands	Typical use
standard mode	Yes	Yes	Running jobs dispatched from Chef 360 Platform
zero mode	No	Yes	Local job testing, CI/CD pipelines, and air-gapped environments
dry-run mode	No	No	Validating a job template’s syntax, interpreters, and dependencies without running it

How-to guides

Run and validate Courier jobs locally: Execute a job in zero mode or validate a job template in dry-run mode.

Skill interpreters: Explore the available interpreters and their command syntax.

Reference

Courier Runner reference: CLI options, job template fields, and output file formats.