Operators Guide

Agent Runners & Services

Learn how to configure and deploy rescile-runners as autonomous agents or daemons to securely execute actions and long-running services.

Edit this page on GitHub

Agent Runners & Services

The Rescile Controller supports executing actions directly via the REST API or passing them to the Action Queue, where connected rescile-runner instances process them.

The rescile-runner enables you to execute workloads (like scripts, Terraform, or background services) securely within isolated network segments (e.g., inside a VPC, on-premise datacenter, or a DMZ).

Runner Execution Modes

To accommodate various networking architectures, runners can be connected in two continuous operating modes, alongside manual execution modes.

1. Agent Mode (Push)

In Agent Mode, runners connect outward to the Rescile Controller using a continuous gRPC multiplexed stream over the standard HTTP/2 endpoint. This is ideal for crossing NAT boundaries and executing workloads without opening inbound firewall ports.

To start a rescile-runner in agent mode, specify the --mode agent flag and provide the Controller URL and an API token.

rescile-runner \
    --mode agent \
    --controller-url http://controller.rescile.local:7600 \
    --api-token my-secret-token \
    --agent-labels "prod,dmz"

The agent immediately connects, registers its profile, and begins listening for dispatched jobs. Execution logs and status updates are pushed in real-time back to the Controller.

2. Daemon Mode (Pull)

In Daemon Mode, the runner acts as a lightweight HTTP server on the target machine. The Rescile Controller is configured to poll this daemon. When an action matches the daemon’s capabilities, the Controller instructs the daemon to pull the action bundle and execute it.

To start a runner in daemon mode:

rescile-runner runner -m daemon --listen 0.0.0.0:3000

To instruct the Controller to connect to this daemon, launch the controller with the daemon URL:

rescile-ce serve --daemon-runner http://10.0.0.5:3000

Capability-Based Routing

When an agent runner connects, it registers a Capability Profile containing:

  • System OS and Architecture (e.g., linux, x86_64)
  • Hostname and IP Address
  • Dynamic Capabilities: Available tools like docker, nix, podman, or wasi.
  • Custom Labels: User-defined tags for workload targeting (e.g., gpu, pci-dss, dmz).

The Controller queues incoming execution requests (Actions) and continuously matches them against connected runners based on their required capabilities. The assignment is only dispatched if a runner satisfies all constraints.

Jobs vs. Services

Actions define a run_mode which instructs the runner on how to manage the process lifecycle:

  • Job (Default): The runner executes the process, waits for it to exit, and reports the exit code (Success/Failure) back to the Controller. Suitable for automation scripts, IaC deployments, or finite data processing tasks.
  • Service: The runner spawns the process in the background and continuously monitors it. If the Controller sends an updated configuration for the action, the runner gracefully restarts the service (Zero-Downtime reconciliation). Suitable for background daemons, web servers, or long-running APIs.

Managing the Action Queue

The Rescile Portal UI provides a Services & Runners dashboard where administrators can:

  • View all actively connected Agent Runners, their hostnames, IP addresses, and capability labels.
  • Monitor the live Action Queue to see Pending, Assigned, Running, Completed, or Failed workloads.
  • Manually intervene by approving pending jobs, forcefully executing them, or cancelling blocked workloads.
  • Trigger actions immediately via Run Action.