Run an agent

An agent is a single process serving one project. It exposes a JSON API over HTTP and a WebSocket event stream; the consoles connect to it.

Start

export STEELFRAME_MASTER_KEY='<a long random secret>'
steelframe agent run

For a local development loop that also serves a same-origin Web GUI:

make dev

Environment variables

Variable	Default	Purpose
STEELFRAME_HOST	0.0.0.0	Bind address (use 127.0.0.1 behind nginx).
STEELFRAME_PORT	7700	Bind port.
STEELFRAME_DB_URL	file:steelframe.db	Turso/libsql database URL.
STEELFRAME_MASTER_KEY	—	Encrypts stored credentials.
STEELFRAME_NO_UPDATE	—	1 skips the release-channel poll and launch update.

All other settings live in the database config table and are edited from the Config surface (TUI, GUI, or API). See Configuration reference.

Delivery profiles

delivery_profile chooses the delivery path:

• live — implement → CI → deploy to staging → staging health checks → merge → deploy to production → production health checks.
• source — no live cluster: once CI is green the PR is rebase-merged to main and the task is done.

pr_merge_method (squash default, rebase on rebase-only repos) is the preferred gh pr merge method.

Capacity and safety controls

Key	Default	Effect
dispatch_min_available_mb	1024	Skip spawning a worker while MemAvailable is below this. 0 disables.
max_compile_slots	1	Host-wide lock around cargo / cargo-clippy so parallel workers do not compile at once. 0 disables.
worker_memory_max	auto	Per-worker cgroup memory cap. auto sizes from host RAM (min 8G, max 16G), off disables.
auto_update_minutes	5	Release-channel poll interval. 0 disables.

The agent fails closed: when worker occupancy or MemAvailable cannot be read, it treats the pool as full rather than over-spawning.

Monitoring production

With health checks configured, the agent periodically probes production. When a check fails enough times it launches an investigation workflow; if the incident is impactful, the agent files an issue and fixes it through the same task_lifecycle path a human would use.

Token usage

The Agents surface (TUI and GUI) counts input and output tokens spent per AI-driven step.

Terminating a run

If a workflow is stuck on an unhandled edge case, terminate it from the run detail on the Dashboard. Termination is recorded in the step log; failure is terminal, so start a fresh run afterwards.

Auto-update and drain

When a newer version is pending, no new workers start until in-flight workers finish (drain). The agent then applies the binary and re-execs. The drain gate fails closed: if the worker count cannot be read, the gate holds and the next watchdog tick retries.