cradle-agent

cradle-agent is the Windows execution engine for Cradle. It starts a target program under the Windows debug API, loads Cradle plugins from disk, broadcasts process/debug events to those plugins, and returns collected check results either to the terminal or to a remote cradle-cli operator.

Cradle currently supports Windows targets only.

Build

From the workspace root:

cargo build (--release) -p cradle-agent

The binary is then written to:

target\<debug\release>\cradle-agent.exe

Running Locally

Local mode runs the target immediately and prints results directly from the agent. This is the fastest mode for when you just want to do local testing

.\cradle-agent.exe --local .\path\to\target.exe

The default execution timeout is 5000ms. You can increase it for slower targets:

.\cradle-agent.exe --local --timeout 15000 .\path\to\target.exe

Running Remotely

Without --local, the agent listens for an operator connection. The operator is usually cradle-cli.

.\cradle-agent.exe .\path\to\target.exe

By default, the agent listens on localhost:9001. In another terminal:

.\cradle-cli.exe localhost:9001

The agent keeps listening after each run so another CLI connection can start the checks again. This behavior can be changed by using the --oneshot flag to exit after the first completed run:

.\cradle-agent.exe --oneshot .\path\to\target.exe

Plugins

At startup, the agent scans the plugin directory for Cradle plugins. On Windows, those are .dll files. The default plugin directory is plugins relative to the current working directory.

.\cradle-agent.exe --plugin-dir .\artifacts .\path\to\target.exe

Plugins must export the Cradle plugin ABI and use a compatible cradle-plugin-api major version. Incompatible or malformed plugin files are reported as warnings and skipped.

Authentication

Use --token to require a shared token from the CLI before it can start a run:

.\cradle-agent.exe --token "dev-secret" .\path\to\target.exe
.\cradle-cli.exe --token "dev-secret" localhost:9001

The token is sent as part of the Cradle connection handshake. If the token does not match, the agent rejects the request.

TLS

The agent can run over plain TCP, use a certificate/key pair, or generate a self-signed certificate for the current process.

Use a certificate and key:

.\cradle-agent.exe --cert .\server.crt --key .\server.key .\path\to\target.exe
.\cradle-cli.exe --tls localhost:9001

The certificate and key can also be supplied through environment variables:

$env:AZ_CRADLE_CERT = "C:\certs\server.crt"
$env:AZ_CRADLE_KEY = "C:\certs\server.key"
.\cradle-agent.exe .\path\to\target.exe

For local testing, generate a temporary self-signed certificate:

.\cradle-agent.exe --auto-cert .\path\to\target.exe
.\cradle-cli.exe --tls --insecure localhost:9001

Options

Usage: cradle-agent.exe [OPTIONS] <BINARY>

Arguments:
  <BINARY>  Path to target binary

Options:
  -p, --port <PORT>              Cradle operator server port [default: 9001]
  -t, --timeout <TIMEOUT>        Execution timeout duration in ms [default: 5000]
  -b, --bind <BIND>              Address to listen on [default: localhost]
      --oneshot                  Execute one remote run, then exit
      --token <TOKEN>            Require a matching CLI auth token
      --cert <CERT>              TLS certificate path [env: AZ_CRADLE_CERT]
      --key <KEY>                TLS private key path [env: AZ_CRADLE_KEY]
      --auto-cert                Generate a temporary self-signed certificate
      --plugin-dir <PLUGIN_DIR>  Plugin directory path [default: plugins]
      --local                    Run without waiting for a CLI connection
  -h, --help                     Print help

Notes

• Target arguments are not exposed by the current CLI surface; pass a target executable path only.
• Remote mode starts a fresh target process for each accepted cradle-cli run
• If the timeout expires before the target exits, the agent terminates the target and still asks plugins for any results collected so far, which is usually none