Execution Modes

Forgecroft supports two execution modes for running plans and applies.

Managed Execution

Default mode. Forgecroft runs your IaC tool in its own secure, isolated environment.

How it works

1. You trigger a plan (manually or via webhook)
2. Forgecroft queues the run
3. A job spawner picks up the run and creates a Kubernetes Job
4. The Job runs in a gVisor sandbox with no service account token
5. Results are reported back and the Job is cleaned up

When to use

• Getting started — quickest path to first plan
• Standard cloud providers (AWS, GCP, Cloudflare)
• No special network requirements
• You don’t need to control the execution environment

Agent Execution

Runs are claimed by a Forgecroft Agent running in your own environment.

How it works

1. You trigger a plan on an agent-mode workspace
2. The run is queued with execution_target: "agent"
3. Your agent polls GET /agent/runs/next and claims the next queued run
4. The agent receives all configuration (credentials, state backend, VCS token) in the response
5. The agent executes the run and reports results back via runner callbacks

When to use

• Runs must execute inside your VPC or private network
• You need access to internal resources (databases, private registries)
• Compliance requires execution in your own environment
• You need custom egress or proxy configuration

Switching Modes

Switch a workspace between modes:

PATCH /workspaces/{id}
{ "execution_target": "agent" }

This field is admin-only. Existing runs are not affected — only new runs use the new mode.

Comparison

Related

• Agent Getting Started — Set up the Forgecroft Agent
• Creating Workspaces — Configure execution_target