Agent

Agent configuration for Crow CI workers.

Minimum Configuration

CROW_SERVER=crow-server:9000
CROW_AGENT_SECRET=<token>

Variable	Description
CROW_SERVER	Server gRPC address (no protocol prefix)
CROW_AGENT_SECRET	Authentication token from server

Parallel Workflows

CROW_MAX_WORKFLOWS=4

By default, agents execute one workflow at a time. Increase based on available resources.

Note

A pipeline often consists of multiple workflows. Match this setting to your environment’s capacity.

Workflow Filtering

Crow routes workflows to agents using two mechanisms:

Method	Description
Labels	Filter by matching key-value pairs
Priority	Prefer agents with higher priority when multiple match

Caution

Label filtering takes precedence. If an agent is excluded by labels, priority has no effect.

Labels

Agents have built-in labels:

Label	Description
backend	Execution backend (docker, kubernetes, local)
type	Agent type
platform	OS/architecture
agent	Agent identifier

Add custom labels to route specific workflows:

# Agent configuration
CROW_AGENT_LABELS='gpu=true,memory=high'

# Workflow configuration (.crow.yaml)
labels:
  gpu: true
  memory: high

Only agents with matching labels will process workflows with those labels.

Priority

When multiple agents match, higher priority agents are preferred:

CROW_AGENT_PRIORITY=100

Use this to prefer agents with more capacity when available.

Agent Types

Global Agents

Admin-managed agents that process all workflows. Configure via environment variables on the agent.

Organization/User Agents

Non-admin users can register agents scoped to their org or user account.

Caution

Scoped agents can only process workflows from their assigned org/user for security isolation.

Remote agent configuration:

CROW_GRPC_ADDR=crow.example.com:9000
CROW_GRPC_SECURE=true
CROW_AGENT_SECRET=<token>
CROW_BACKEND=docker

Tip

When global agents exist alongside scoped agents, add custom labels to ensure workflows route to the intended agent.

Multi-Org Agents

Note

Admin-only feature. This is for security reasons: otherwise it would be possible to route workflows of other users to a custom agent.

Process workflows from multiple specified organizations or repositories.

# Multiple orgs (pipe-separated)
CROW_CUSTOM_LABELS='org=1|2|3'

# Alternative syntax (comma-separated, merged internally)
CROW_CUSTOM_LABELS='org=1,org=2,org=3'

# Limit to specific repos
CROW_CUSTOM_LABELS='org=myorg,repo=myorg/specific-repo'

Multi-org labels appear highlighted in the agent list:

Multi-org Agent

Backend Options

Configure backend-specific settings at the agent level. See environment variables for all CROW_BACKEND_* options.

Local Backend Sandboxing

Note

macOS only. Automatically disabled on other platforms.

Enable process isolation using macOS sandbox-exec:

CROW_BACKEND_LOCAL_SANDBOX_LEVEL=standard

Level	Network	System Access	Use Case
none	✅ Full	✅ Full	Trusted code only
standard	✅ Full	⚠️ Limited	Most CI/CD workloads
strict	❌ Blocked	❌ Minimal	Offline builds, maximum isolation

Standard level details:

Allows	Denies
Network access (npm, go get, pip)	Writing outside workflow dirs
System libraries and frameworks	Sensitive user dirs (Documents, Desktop)
Shell configs (.bashrc, .zshrc)	SSH private keys
Workflow temp directories

none runs processes without isolation. Only use with fully trusted code.

Note

strict blocks network access, breaking most CI/CD workflows that download dependencies.