---
title: Orchestrator
---

# Orchestrator

Multi-agent task execution with cache coordination.

## Overview

Orchestrator supervises agents that claim and execute tasks from a shared cache.

## Architecture

```
Orchestrator → Reads instructions/INSTRUCTIONS.md → Spawns agents → Creates DAGs
Agent → Claims task → Executes → Updates cache
```

Cache keys:
```
dag:<goal>:nodes    # Tasks
dag:<goal>:deps     # Dependencies
task:<id>           # Status
task:<id>:lock      # Locks
agent:<name>:*      # Registry
```

## Features

- **Tasks**: LLM generates DAG from instructions
- **Locking**: Time-limited task leases
- **States**: `BLOCKED → READY → RUNNING → DONE/FAILED`
- **Control**: Heartbeat files accept `PAUSE`, `RESUME`, `DROP-TASK`, etc.
- **Spawning**: Each agent gets instruction file, heartbeat, goal ID

## Files

```
systemg.yaml                    # Orchestrator service config
instructions/INSTRUCTIONS.md    # Agent declarations
instructions/*.md               # Per-agent instructions
instructions/heartbeat/*.md     # Control files
docs/*.md                       # Example specs
```

## Configuration

**systemg.yaml:**
```yaml
version: "1"
logs:
  sink: none
status:
  snapshot_mode: summary
  snapshot_interval_secs: 10
services:
  redis:
    command: "redis-server"
  orchestrator:
    command: >
      porki
      --role orchestrator
      --instructions instructions/INSTRUCTIONS.md
      --redis-url redis://127.0.0.1:6379
    env:
      vars:
        PORKI_LLM_MAX_CONCURRENCY: "6"
        PORKI_LLM_CONCURRENCY_WAIT_SECONDS: "900"
    depends_on: ["redis"]
    spawn:
      mode: dynamic
      limit: 10
```

The orchestrator example disables systemg-managed service output capture because
agent workloads can be noisy. Use your regular logging pipeline for production
agent output, and reserve `sysg logs` for services that opt into `logs.sink:
file`.

The status cache uses summary snapshots every 10 seconds to avoid expensive
process tree discovery across many dynamic children.

`PORKI_LLM_MAX_CONCURRENCY` raises the number of global LLM leases available
across agents, and `PORKI_LLM_CONCURRENCY_WAIT_SECONDS` controls how long agents
wait for a lease before timing out.

**instructions/INSTRUCTIONS.md:**
```markdown
## Agents
### research_agent
- Goal: goal-001
- Heartbeat: ./instructions/heartbeat/research.md
```

## DAG Format

```json
{
  "goal_id": "goal-001",
  "nodes": [{"id": "task-001", "title": "Research", "priority": 10}],
  "edges": [{"source": "task-001", "target": "task-002"}]
}
```

## Usage

```bash
# Setup
$ cd examples/orchestrator
$ pip install porki

# Run
$ redis-server
$ sysg start

# Monitor
$ sysg status
$ redis-cli KEYS "*"

# Control
$ echo "PAUSE" >> ./instructions/heartbeat/research.md
```

## Validation

Use `sysg status` and Redis keys to validate runtime behavior. Package-level
runtime tests execute in the `porki` repository.

## Links

- [Configuration](/how-it-works/configuration)
- [How It Works](/how-it-works)
