agent_commands. They represent every instruction the UI gives to a gateway — provisioning agents, approving pairings, connecting providers, restarting services, and more.
State machine
1
UI inserts a command
A server action writes a row to
agent_commands with status = 'pending'.2
Runner leases the command
The runner daemon picks it up via Realtime subscription or polling, then calls
lease_command(p_gateway_slug) to atomically claim it.3
Runner executes
The runner maps the command action to a shell operation (e.g.
add-agent.sh for provision) and runs it.4
Runner reports results
On completion, the runner writes
stdout, stderr, exit_code, and final status (done or failed) back to the row.RPC lifecycle calls
The runner uses four RPCs to manage command state:
Connection actions (
auth_*) call start_command and complete_command/fail_command themselves — they don’t go through the standard shell-command path.