Managing Agents¶

Agents are registered with a Finch service and managed through finchctl. Each agent has a unique RID generated at registration time.

List agents¶

finchctl agent list finch.example.com

Returns a table of all registered agents: RID, hostname, log sources, metrics, profiles, and labels.

# JSON output
finchctl agent list --output.json finch.example.com

Describe an agent¶

finchctl agent describe \
  --agent.rid rid:finch:8d134b24c2541730:agent:59ddbb5d-73b2-45bf-95d3-5520dcf37618 \
  finch.example.com

Returns full details for a single agent. Useful for inspecting the current configuration before editing, or for exporting a YAML file to re-use on registration.

# Export to YAML for re-registration
finchctl agent describe \
  --agent.rid rid:finch:8d134b24c2541730:agent:59ddbb5d-73b2-45bf-95d3-5520dcf37618 \
  --output.json \
  finch.example.com | \
  yq --input-format json --output-format yaml > agent.yaml

Edit an agent¶

Update the log sources, metrics, profiles, or labels of a registered agent. The agent's RID, hostname and node type cannot be changed.

finchctl agent edit finch.example.com \
  --agent.rid rid:finch:8d134b24c2541730:agent:59ddbb5d-73b2-45bf-95d3-5520dcf37618 \
  --agent.logs.journal \
  --agent.logs.docker \
  --agent.metrics \
  --agent.labels env=production

After editing, download a fresh config and redeploy it so Alloy picks up the changes:

finchctl agent config \
  --agent.rid rid:finch:8d134b24c2541730:agent:59ddbb5d-73b2-45bf-95d3-5520dcf37618 \
  --agent.config web-01-new.cfg \
  finch.example.com
finchctl agent deploy \
  --agent.config web-01-new.cfg \
  root@172.17.0.4

agent edit also accepts --agent.file to load options from a YAML file:

finchctl agent edit \
  --agent.file agent.yaml \
  --agent.rid rid:finch:8d134b24c2541730:agent:59ddbb5d-73b2-45bf-95d3-5520dcf37618 \
  finch.example.com

Deregister an agent¶

Removes the agent record from the Finch database and immediately invalidates its JWT. Any subsequent write attempts from that agent are rejected.

finchctl agent deregister \
  --agent.rid rid:finch:8d134b24c2541730:agent:59ddbb5d-73b2-45bf-95d3-5520dcf37618 \
  finch.example.com

No undo

Deregistering permanently removes the agent record. To re-add the agent, run agent register again. A new RID and token will be issued.

Optionally follow up with a full teardown of the Alloy installation on the host:

finchctl agent teardown root@172.17.0.4

See Recover an Agent Breach for the full deregister → re-register → redeploy workflow.