Skip to main content

​
Pool Commands

Agent pools group workers and stewards with shared concurrency limits and auto-scaling behavior. Pools are useful for controlling resource usage and distributing work across multiple agent instances.

​
Commands

​
sf pool list

List all agent pools. 
sf pool list
Output: 
ID          NAME            SIZE    ACTIVE  STATUS
pool-abc    worker-pool     5       2       active
pool-def    steward-pool    3       1       active

2 pool(s)
Options:
​
--json
boolean
Output in JSON format

​
sf pool create

Create a new agent pool. 
sf pool create <name> [options]
Arguments:
​
name
string
required
Pool name (unique identifier)
Options:
​
--size
number
Maximum concurrent agents (default: 5)
​
--agent-type
string
Agent type configuration. Format: role[:workerMode|stewardFocus][:priority][:maxSlots][:provider][:model]Examples:
  • worker:ephemeral:100:5 - Ephemeral workers, priority 100, max 5 slots
  • worker:persistent:50 - Persistent workers, priority 50
  • steward:merge - Merge stewards
​
--auto-scale
boolean
Enable auto-scaling (spawn agents based on workload)
​
--min-agents
number
Minimum number of agents to keep running (auto-scale only)
​
--max-agents
number
Maximum number of agents to spawn (auto-scale only)
Examples: 
# Create a pool for ephemeral workers
sf pool create worker-pool --size 10 --agent-type "worker:ephemeral"

# Create an auto-scaling pool
sf pool create auto-workers --size 20 --auto-scale --min-agents 2 --max-agents 10

# Create a steward pool for merge review
sf pool create merge-stewards --size 3 --agent-type "steward:merge"

​
sf pool show

Show details for a specific pool. 
sf pool show <pool-id>
Arguments:
​
pool-id
string
required
Pool element ID
Example: 
sf pool show pool-abc123
Output: 
Pool: worker-pool (pool-abc123)
Size: 10
Active Agents: 3
Auto-scale: enabled
  Min: 2
  Max: 10
Agent Type: worker:ephemeral

Active Agents:
  - el-worker1 (running)
  - el-worker2 (running)
  - el-worker3 (idle)

​
sf pool update

Update pool configuration. 
sf pool update <pool-id> [options]
Arguments:
​
pool-id
string
required
Pool element ID
Options:
​
--size
number
Update maximum concurrent agents
​
--auto-scale
boolean
Enable/disable auto-scaling
​
--min-agents
number
Update minimum agents
​
--max-agents
number
Update maximum agents
Example: 
sf pool update pool-abc123 --size 15 --max-agents 12

​
sf pool delete

Delete an agent pool. 
sf pool delete <pool-id>
Arguments:
​
pool-id
string
required
Pool element ID to delete
Options:
​
--force
boolean
Force deletion even if pool has active agents
Example: 
sf pool delete pool-abc123 --force

​
sf pool status

Show pool status with active agent information. 
sf pool status <pool-id>
Arguments:
​
pool-id
string
required
Pool element ID
Example: 
sf pool status pool-abc123
Output: 
Pool: worker-pool (pool-abc123)
Status: active
Utilization: 3/10 (30%)

Active Sessions:
  el-worker1: running (task: task-123)
  el-worker2: running (task: task-456)
  el-worker3: idle

Available Slots: 7

​
Pool Configuration

Agent pools support several configuration patterns:

​
Worker Pools

# Ephemeral workers (spawn per task)
sf pool create ephemeral-pool --agent-type "worker:ephemeral:100:10"

# Persistent workers (long-running sessions)
sf pool create persistent-pool --agent-type "worker:persistent:50:5"

​
Steward Pools

# Merge stewards
sf pool create merge-pool --agent-type "steward:merge"

# Documentation stewards
sf pool create docs-pool --agent-type "steward:docs"

# Custom stewards
sf pool create custom-pool --agent-type "steward:custom"

​
Auto-Scaling

Pools can auto-scale based on workload: 
sf pool create auto-pool \
  --size 20 \
  --auto-scale \
  --min-agents 2 \
  --max-agents 15 \
  --agent-type "worker:ephemeral"
  • Maintains at least --min-agents running
  • Scales up to --max-agents based on ready tasks
  • Scales down when workload decreases

​
Best Practices

Use pools to isolate different types of work (frontend, backend, infrastructure) with appropriate concurrency limits.
Pool size limits apply globally across all agents in the pool. Set --size based on your available rate limits and resources.

Agent Commands

Register and manage agents

Daemon

Control dispatch daemon

Build docs developers (and LLMs) love

Get started for freeTalk to us