Local Runner

The Safeguard runner is a command-line process that executes Safeguard workflows on your machine. It runs the same step graph the cloud runner does, but on your filesystem, against your local Git repositories, with access to your local Docker daemon and kubeconfig.

Think of it like claude-code for security: an agent that reads your codebase, proposes changes with Griffin, runs tests, and iterates — without leaving your laptop.

When to Use the Runner

• You want Griffin to fix vulnerabilities against code you haven't pushed yet.
• Your repository is private and you can't (or won't) give a cloud service OAuth access.
• You're working in an air-gapped or heavily restricted environment.
• You want to debug a workflow locally before promoting it to cloud execution.
• You need to run a workflow against a local Kubernetes cluster (kind, k3d, Docker Desktop).

Install

macOS

brew install safeguard/tap/runner

Windows

winget install Safeguard.Runner

Linux

curl -fsSL https://get.safeguard.sh/runner | sh

Or pull the container image:

docker pull ghcr.io/safeguard-sh/runner:latest

First Run

safeguard-runner login
# Opens browser for OAuth device-flow authentication.

safeguard-runner run ./workflows/auto-fix.yaml
# Executes the workflow against the current directory.

How It Works

The runner is a thin process that:

1. Reads the workflow YAML.
2. Resolves uses: step references from Safeguard's signed step registry (cached locally after first run).
3. Executes steps in order (or in parallel where declared).
4. Calls Safeguard cloud APIs for tasks that need cloud data — vulnerability lookups, Eagle classification, Lino policy evaluation — but keeps source code, SBOMs, and proposed diffs local unless you opt-in to upload.
5. Streams progress to your terminal and, optionally, to a local web UI at http://localhost:9090.

Modes

Interactive

safeguard-runner run ./workflows/auto-fix.yaml --interactive

Asks for confirmation before:

• Writing files.
• Running shell commands.
• Pushing to remote.
• Uploading anything to Safeguard cloud.

Mirrors the consent model of the Desktop App.

Headless

safeguard-runner run ./workflows/auto-fix.yaml --headless

Runs without prompts. Suitable for:

• CI pipelines where the job is trusted.
• Scheduled local jobs (cron, launchd, Task Scheduler).
• Scripts that glue multiple workflows together.

Agent Mode

safeguard-runner agent --repo ./path/to/repo --goal "fix critical CVEs on main"

Griffin plans the workflow, executes it, and iterates until the goal is met or it needs your input. This is the closest equivalent to claude-code for Safeguard.

Local Web UI

Run safeguard-runner ui to open a local dashboard at http://localhost:9090:

• Live step timeline.
• Terminal-style log viewer.
• Proposed diff browser with accept / reject.
• Proposed shell command viewer with allow / deny.

The UI is self-contained. No data leaves your machine unless you explicitly accept a cloud step.

Configuration

A .safeguard/runner.yaml in your repo configures per-project defaults:

runner:
  version: ">=1.4.0"
  allow_cloud_steps: true
  allow_shell_steps: ["npm install", "npm test", "git *"]
  deny_shell_steps: ["rm -rf *"]
  upload_sbom: manual     # "never" | "manual" | "auto"
  data_residency: US

A global config at ~/.safeguard/runner.yaml sets defaults across projects.

Supported Steps

The runner supports the same step library as the cloud runner, with a few exceptions:

• Cloud-only steps (e.g., hosted workflow webhooks) are skipped or redirected.
• Steps that need local access (e.g., docker-scan, git-commit) work better on the runner.

See Workflows for the full step reference.

Resource Usage

• Idle: ~60 MB RAM, ~0% CPU.
• Active workflow: 200–600 MB RAM depending on SBOM size; bursts of CPU during analysis.
• Disk: cached step binaries + vulnerability snapshot; typical total ~1–3 GB.

Updates

safeguard-runner update

Releases follow semver. Major version bumps may require workflow changes — a changelog and migration notes ship with each major release.

Self-Hosted Cloud Runner (Kubernetes)

For team-wide self-hosted execution (not just laptops), deploy the runner as a Kubernetes operator:

helm install safeguard-runner safeguard/runner \
  --namespace safeguard-system \
  --set tenant.id=$SAFEGUARD_TENANT \
  --set tenant.apiKey=$SAFEGUARD_API_KEY \
  --set runner.replicas=3

The operator registers the runners with the cloud workflow scheduler. Workflows declaring runs-on: self-hosted execute on your cluster.

Security

• The runner verifies signed step manifests before executing any step code.
• The runner enforces the allow_cloud_steps, allow_shell_steps, deny_shell_steps lists at step-dispatch time.
• Credentials are read from the OS keychain or environment; never stored in plaintext.
• Every run produces a local, append-only JSON audit log.

Related

• Workflows — workflow language and step reference.
• Desktop Application — the runner is embedded in the desktop app.
• CLI — safeguard CLI (the runner is the workflow-executing cousin of the CLI).
• Griffin AI — the model agent mode invokes.