Core concepts

SI Fabrik follows the Symphony service specification, with extensions for sandboxes, managed git, links and guardrails. These are the terms the rest of the docs use.

Project#

A project is a git repository plus its WORKFLOW.md. Each project has its own orchestrator: a state machine that polls the tracker, dispatches tasks, reconciles running work and schedules retries. You start, stop and pause orchestrators per project. Pausing stops new dispatches while running agents continue.

In Local mode a project lives on your Mac. In Remote mode it lives on a harnessd server, which clones the repository into its data directory.

Task#

A task (the spec says issue) comes from the project's tracker: the built-in board, ClickUp or GitHub Issues. SI Fabrik normalizes every task to the same shape: id, identifier (such as HAR-12, CU-86b1x or GH-42), title, description, priority, state, labels, blocked_by, url and timestamps.

A task is eligible when:

• its state is one of tracker.active_states and not one of tracker.terminal_states;
• it has every label in tracker.required_labels;
• it isn't blocked (all of its blockers are in a terminal state) and isn't waiting on a linked task;
• it isn't parked by a guardrail.

Eligible tasks are dispatched by priority (1 is most urgent; no priority goes last), then oldest first, then by identifier. Concurrency is capped by agent.max_concurrent_agents, per-state caps, and the host-wide limit.

Workspace#

Every task gets its own workspace: a directory under workspace.root named after the task identifier. With managed git (the default) it's a fresh clone of your project on the task branch symphony/<task-id>. Workspaces are reused across attempts at the same task and removed when the task reaches a terminal state, after the branch is saved.

Attempt and turn#

An attempt is one run of the agent process on a task. Within an attempt, the agent works in turns:

• The first turn gets your full prompt, rendered from the WORKFLOW.md body.
• Later turns get a short continuation message, while the task is still active, up to agent.max_turns.
• Claude Code keeps one long-lived process per attempt, so continuation turns reuse the same live session.

If an attempt fails, the task is retried with exponential backoff (10 s, 20 s, 40 s … up to agent.max_retry_backoff_ms). If the attempt ends normally but the task is still active, a continuation check runs one second later.

Hand-off#

The agent finishes by moving the task to a hand-off state: any state that is neither active nor terminal, such as Human Review, ClickUp's review, or a human-review label on GitHub. When reconciliation sees that move:

• the in-flight turn is allowed to finish, so its summary and token usage are kept;
• no further turns start, and the run is force-stopped after 90 seconds;
• the task branch is saved, pushed, and a pull request is opened or updated.

Moving a task to a terminal state (such as Done or Canceled) stops its agent immediately and cleans up the workspace.

Sandbox#

A sandbox is where the agent process runs:

• Docker: a hardened container per task on this Mac or server, with no capabilities, a read-only root filesystem and an allowlisted network.
• Cloudflare: a Cloudflare Container per task through a bridge Worker you deploy. Model keys and tracker tokens never enter Cloudflare.
• Host: no sandbox. The agent runs as your user. Use this only with trusted repositories.

Tracker tools#

Agents update their task through the symphony MCP server: tools such as board_set_state, clickup_comment or github_add_labels. The tools run on the SI Fabrik host with SI Fabrik's tracker credentials, so the agent never sees a tracker token. Each run gets its own MCP URL with a token scoped to its task.

Guardrails#

The spec retries failed work forever. SI Fabrik adds limits that stop scheduling (never a running turn): daily budgets, a cost cap per task, parking a task after repeated failures, and pausing a project after a failure streak. See Budgets and limits.

The Symphony specification#

See also#

• Turns, retries and hand-off
• Workspaces and hooks
• Choose a sandbox