Agents

Agents are distributed workers that execute pipeline jobs. They run on your own infrastructure (physical machines, VMs, containers, or cloud instances) and communicate with the orchestrator to claim jobs, stream logs, and report metrics.

🔌 Connecting an Agent

1. Create an Agent Token

Navigate to Settings → Agent Tokens (for personal projects) or Organization Settings → Agent Tokens (for org projects) and click Create Token. Give it a descriptive label like “linux-builder” or “mac-studio”.

2. Start the Agent

Copy the connection command shown after token creation and run it on your machine:

Docker Bash PowerShell

docker run --rm ghcr.io/actionforge/actrun agent --token <TOKEN>

actrun agent --token <TOKEN>

actrun agent --token <TOKEN>

The agent connects to the orchestrator, begins sending heartbeats, and polls for available jobs. Once online, it appears in the Agents page.

🏷️ Agent Labels

Labels let you target specific agents for specific jobs, for example by OS, architecture, installed software, or environment.

To manage labels, go to Agents, select an agent, and edit its Labels. Labels use a key=value format (e.g. os=linux, arch=arm64, gpu=true).

When a pipeline run specifies required labels, only agents matching all labels will claim the job.

📊 Monitoring

Agent List

The Agents page shows all connected agents with their current status:

• Online: Agent is connected and ready
• Busy: Agent is executing a job
• Offline: Agent has disconnected

The list updates in real-time, so there is no need to refresh.

Agent Metrics

Click on an agent to view its detail page with system metrics over a rolling 6-hour window:

• CPU usage: Per-core and aggregate utilization
• Memory: Used, available, and total
• Network: Bytes sent and received

🗑️ Removing an Agent

On the agent detail page, click Remove to unregister the agent from the orchestrator. The agent process on the host machine should be stopped separately.

For programmatic management, see REST API.