How the Agent Works

The polling model

The agent does not receive inbound connections. It connects outbound to the Forgecroft API and polls for queued runs assigned to your organization. When a run is available, the agent claims it, executes it, and reports back.

This means no inbound firewall rules, no webhooks, and no public IP required on the agent host.

What happens during a run

1. Claim — The agent polls GET /agent/runs/next. When a queued run is available for its org, it is claimed and a one-time runner token is issued.
2. Fetch source — The agent clones or fetches the configured repository at the specified branch and commit SHA.
3. Execute — The agent runs tofu init and then tofu plan or tofu apply inside the source root. It streams log lines back to Forgecroft as they are produced.
4. Report — Phase transitions (plan start, plan end, apply start, apply end) and the final status are posted back. Forgecroft updates the run record and triggers notifications.

How credentials work

The Forgecroft API key authenticates the agent to Forgecroft. It does not grant cloud access.

Cloud credentials come from the environment where the agent runs — the same way they would if you ran tofu directly on that machine:

• AWS — instance profile, IRSA, environment variables, or ~/.aws/credentials
• GCP — service account attached to the VM, Workload Identity, or GOOGLE_APPLICATION_CREDENTIALS
• Azure — managed identity, environment variables, or CLI credentials

This is intentional. The agent model assumes credentials are already present in the execution environment. If you want Forgecroft to inject credentials, use managed execution instead.

Security boundary

The agent runs inside your network. Forgecroft only sees what the agent sends back — log lines, plan summaries, change counts, and status. Your cloud credentials never leave your environment.

The runner token is single-use and scoped to one run. It expires when the run reaches a terminal state. The org-level API key is used only to claim runs, not during execution.

Heartbeat and timeouts

The agent sends a heartbeat to Forgecroft every 30 seconds during a run. If Forgecroft does not receive a heartbeat for 10 minutes — because the agent crashed or lost network — it marks the run as timed_out.

Timed-out runs can be retried manually from the Forgecroft console.

Next

Learn how to run the agent reliably in production: Running Reliably.