Tutorials¶

Tutorials walk through concrete operational scenarios step by step. Each one starts with a specific situation, explains what is happening under the hood, and ends with the stack and all agents back in a known-good state.

All tutorials assume a running Finch stack and at least one enrolled agent. If you have not yet deployed a stack, start with Deploy the Stack.

Recover an Agent Breach¶

An agent's JWT or configuration file was exposed. The agent must be deregistered immediately to revoke the token, then re-enrolled with a fresh credential.

Covers: agent deregister · agent register · optional full teardown · agent deploy

Rotate mTLS Certificates¶

The mTLS client certificate issued when the stack was deployed expires after 90 days. Rotate it proactively to keep finchctl access uninterrupted.

Covers: service rotate-certificate · certificate expiry check · no agent impact

Rotate the Signing Secret¶

A break-glass operation that replaces the JWT signing secret and immediately invalidates every enrolled agent's token. Use this when the server-side secret is suspected to have been exposed, or when a full token reset is required.

Covers: service rotate-secret · agent config · agent deploy · re-enrolment loop

Re-enroll an Agent¶

Shared steps for pushing a fresh Alloy configuration to an agent host after a token is invalidated. Covers both cases: refreshing a token for an existing agent record (agent config) and re-registering after a deregister (agent register). Includes Windows manual instructions.

Covers: agent config · agent register · agent deploy · Windows manual steps