Running the Agent Reliably

Requirements

• git — to clone source repositories
• tofu (or terraform) — the IaC tool your workspaces use
• Outbound HTTPS to api.forgecroft.com
• Cloud credentials in the execution environment

As a systemd service

Suitable for a long-lived VM where cloud credentials come from an instance profile or environment variables.

/etc/systemd/system/forgecroft-agent.service

[Unit]
Description=Forgecroft Agent
After=network.target

[Service]
ExecStart=/usr/local/bin/forgecroft-agent
Restart=on-failure
RestartSec=10
Environment=FORGECROFT_API_URL=https://api.forgecroft.com
Environment=FORGECROFT_API_KEY=fc_live_...
# Cloud credentials go here or come from instance profile

[Install]
WantedBy=multi-user.target

systemctl enable --now forgecroft-agent

On AWS, omit explicit credentials entirely if the VM has an instance profile with the required permissions. The agent inherits them from the environment automatically.

As a Docker container

Suitable when you want to isolate the agent’s environment or run it alongside other containers.

docker run -d \
  --name forgecroft-agent \
  --restart unless-stopped \
  -e FORGECROFT_API_URL=https://api.forgecroft.com \
  -e FORGECROFT_API_KEY=fc_live_... \
  ghcr.io/forgecroft/forgecroft/agent:latest

If your cloud credentials use environment variables (e.g. AWS_ACCESS_KEY_ID), pass them as additional -e flags. If using a mounted credentials file, use -v ~/.aws:/root/.aws:ro.

On Kubernetes

Suitable when credentials come from IRSA (AWS), Workload Identity (GCP), or a pod identity system.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: forgecroft-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: forgecroft-agent
  template:
    metadata:
      labels:
        app: forgecroft-agent
    spec:
      serviceAccountName: forgecroft-agent  # IRSA or Workload Identity here
      containers:
        - name: agent
          image: ghcr.io/forgecroft/forgecroft/agent:latest
          env:
            - name: FORGECROFT_API_URL
              value: https://api.forgecroft.com
            - name: FORGECROFT_API_KEY
              valueFrom:
                secretKeyRef:
                  name: forgecroft-agent
                  key: api-key

Run a single replica. The agent claims runs one at a time — multiple replicas do not increase parallelism in the current model.

Troubleshooting

• Runs stay queued — check that the agent is running and can reach api.forgecroft.com over HTTPS. Check the workspace execution mode is set to agent.
• Plans fail immediately — usually a credentials or permissions issue. Run tofu init manually on the agent host with the same environment to isolate the problem.
• Runs time out — the agent stopped sending heartbeats. Check for crashes, OOM kills, or network interruptions. Look at the agent process logs.
• State errors — the state backend is unreachable or the credentials lack access to the bucket. Verify bucket permissions separately from cloud provider credentials.