Projects
WORKFLOW.md reference
Every front-matter key SI Fabrik reads, with its type, default and effect.
This page lists every key in the YAML front matter of WORKFLOW.md. Keys from the Symphony specification come first; SI Fabrik's extension keys follow. Unknown keys are ignored. For the prompt body, see Prompt template.
Values written as $NAME or ${NAME} are resolved on the host from the project and global environments. See Environment and variables.
tracker#
Where tasks come from.
| Key | Type | Default | Description |
|---|---|---|---|
tracker.kind | string | required | local, clickup or github. |
tracker.provider | map | {} | Adapter settings; see Trackers and provider keys below. |
tracker.active_states | list or comma-separated string | by kind | States that are dispatched to agents. Must not be empty. |
tracker.terminal_states | list | by kind | States that stop the agent and clean up the workspace (the branch is saved first). |
tracker.board_states | list | by kind | Board columns, in order. For ClickUp, the list's own statuses are used unless you set this. |
tracker.required_labels | list | [] | Only tasks with all of these labels are dispatched. |
States are matched case-insensitively after trimming.
| Kind | active_states | terminal_states | board_states |
|---|---|---|---|
local | Todo, In Progress | Done, Canceled | Backlog, Todo, In Progress, Human Review, Done, Canceled |
clickup | to do, in progress | complete, closed, done | to do, in progress, review, complete (or the list's statuses) |
github | open | closed | open, closed |
Tracker provider keys#
| Kind | Key | Default | Description |
|---|---|---|---|
local | path | .symphony/board.json | Board file, relative to WORKFLOW.md. |
local | prefix | HAR | Identifier prefix, as in HAR-12. The wizard uses the first three letters of the project name. |
clickup | api_token | $CLICKUP_API_TOKEN | Personal token (pk_…). token is accepted as an alias. |
clickup | sprint_folder_id | A Sprints folder: use the current sprint. | |
clickup | list_id / list_ids | Fixed list or lists. Set this or sprint_folder_id. | |
clickup | assignee | me or a user id. Other tasks aren't dispatched. | |
clickup | include_subtasks | true | Include subtasks. |
clickup | api_url | https://api.clickup.com/api/v2 | API base URL. |
github | repo | required | owner/name. |
github | token | $GITHUB_TOKEN, then gh auth token | API token. |
github | exclude_labels | [human-review, blocked] | Issues with any of these labels aren't dispatched. |
github | api_url | https://api.github.com | API base URL (GitHub Enterprise). |
polling#
| Key | Type | Default | Description |
|---|---|---|---|
polling.interval_ms | integer | 30000 | How often the tracker is polled and running work reconciled. Minimum 1000. The wizard writes 15000. |
workspace#
| Key | Type | Default | Description |
|---|---|---|---|
workspace.root | path | <temp>/symphony_workspaces/<project> | Parent folder of the task workspaces. ~ and $VAR are expanded; relative paths resolve against the folder of WORKFLOW.md. The wizard writes ~/HarnessWorkspaces/<project>. |
Note
Without workspace.root, each project gets its own folder under the system temporary directory, symphony_workspaces/<project>, rather than one folder shared by every project. Sharing would let one project see or remove another's workspaces.
hooks#
Shell scripts run at points in a workspace's life. See Workspaces and hooks.
| Key | Type | Default | Description |
|---|---|---|---|
hooks.after_create | string | Runs once when a workspace is created. A failure removes the new workspace and fails the attempt. | |
hooks.before_run | string | Runs before every attempt. A failure fails the attempt. | |
hooks.after_run | string | Runs after every attempt. Failures are ignored. | |
hooks.before_remove | string | Runs before a workspace is removed. Failures are ignored. | |
hooks.timeout_ms | integer | 60000 | Timeout for each hook. Must be positive. |
agent#
| Key | Type | Default | Description |
|---|---|---|---|
agent.max_concurrent_agents | integer | 10 | Agents running at once in this project. The host-wide limit also applies. |
agent.max_turns | integer | 20 | Turns per attempt. Must be positive. |
agent.max_retry_backoff_ms | integer | 300000 | Cap on the exponential retry delay (10 s × 2ⁿ). |
agent.max_concurrent_agents_by_state | map | {} | Per-state caps, for example { "in progress": 2 }. |
runner#
| Key | Type | Default | Description |
|---|---|---|---|
runner.kind | string | claude_code | claude_code or codex. runner: codex (a plain string) also works. Without runner, a workflow that has a codex: block and no claude: block uses Codex. |
claude#
Settings for the Claude Code runner.
| Key | Type | Default | Description |
|---|---|---|---|
claude.command | string | claude | The Claude Code executable. |
claude.model | string | Claude Code's default | Passed as --model, for example claude-opus-5-5. |
claude.permission_mode | string | bypassPermissions | bypassPermissions, acceptEdits, default or plan. bypassPermissions is high-trust: use it with a sandbox. |
claude.allowed_tools | list | [] | Passed as --allowedTools. |
claude.disallowed_tools | list | [] | Passed as --disallowedTools. |
claude.append_system_prompt | string | Added to SI Fabrik's own system prompt. | |
claude.effort | string | low, medium, high, xhigh or max (--effort). | |
claude.max_budget_usd | number | Claude Code stops a session that would cost more (--max-budget-usd). | |
claude.extra_args | list | [] | Extra command-line arguments. |
codex#
Settings for the Codex runner. The three timeouts apply to both runners, as in the Symphony spec.
| Key | Type | Default | Description |
|---|---|---|---|
codex.command | string | codex app-server | The Codex app-server command. |
codex.model | string | Model, for example gpt-5.5-codex. | |
codex.approval_policy | any | never | Passed through to Codex unchanged. Command and file-change approvals are accepted for the session. |
codex.thread_sandbox | any | workspace-write | Passed through unchanged. |
codex.turn_sandbox_policy | any | Passed through unchanged as the turn's sandbox policy. | |
codex.turn_timeout_ms | integer | 3600000 | Silence timeout: a turn fails after this long without agent output. |
codex.read_timeout_ms | integer | 5000 | Timeout for protocol reads. |
codex.stall_timeout_ms | integer | 300000 | A run with no activity for this long is stopped and retried. 0 turns it off. The wizard writes 600000. |
docker#
The Docker image and container settings. They also configure the image and environment of Cloudflare sandboxes.
| Key | Type | Default | Description |
|---|---|---|---|
docker.enabled | boolean | true if a docker: block exists, else false | Run agents in Docker. sandbox.provider overrides it. |
docker.image | string | harness-agent:latest | Agent image. With the browser on, the default becomes harness-agent-browser:latest. |
docker.network | string | A Docker network to use instead of the egress proxy: no allowlist, and the model credential enters the container. Refused by the sandbox floor. | |
docker.env | list | [] | Host environment variable names passed into the sandbox. Push tokens and model credentials are never passed. |
docker.cpus | number | no limit | CPU limit (--cpus). |
docker.memory | string | 8g | Memory limit (--memory), for example 4g. |
docker.extra_args | list | [] | Extra docker run arguments. Refused by the sandbox floor. |
sandbox#
Where agents run and what they can reach. See Network policy.
| Key | Type | Default | Description |
|---|---|---|---|
sandbox.provider | string | docker when docker.enabled, else host | docker, cloudflare or host. host is refused by the sandbox floor. |
sandbox.network.mode | string | allowlist | allowlist or open (any host, still through the egress proxy; not recommended). |
sandbox.network.allow | list | [] | Extra hosts: host, *.domain, host:port or an IP. |
sandbox.network.use_defaults | boolean | true | Include the host-wide default list (Settings → Sandbox, or sandbox.network.default_allow on a server). |
sandbox.hooks | string | sandbox | sandbox runs hooks in a disposable container with the agent's isolation; host runs them on the host (refused by the sandbox floor). |
sandbox.read_only_root | boolean | true | Read-only root filesystem for agent containers. /workspace, /tmp and $HOME stay writable. false is refused by the sandbox floor. |
gateway#
Route model traffic through an LLM gateway such as LiteLLM. Unset fields fall back to Settings → Model Gateway. See Model gateway.
| Key | Type | Default | Description |
|---|---|---|---|
gateway.enabled | boolean | Settings default | false opts this project out. A gateway: block without enabled turns it on. |
gateway.base_url | string | Settings | Gateway URL, for example http://localhost:4000. |
gateway.api_key | string | Settings key | Use $VAR, never an inline key. |
gateway.auth_header | string | bearer | bearer sets ANTHROPIC_AUTH_TOKEN; x-api-key sets ANTHROPIC_API_KEY. |
gateway.models | map | Settings | Slots: opus, sonnet, haiku, subagent, codex. |
gateway.headers | map | {} | Extra request headers, for example { X-Team: platform }. |
gateway.tags | boolean | true | Send x-litellm-tags: harness,project:<name>,issue:<id>. |
gateway.disable_experimental_betas | boolean | false | Set true if the proxy returns 400 "Extra inputs are not permitted". |
gateway.wire_api | string | responses | Codex only: responses or chat. |
git#
Managed task branches. See Branches and pull requests.
| Key | Type | Default | Description |
|---|---|---|---|
git.manage_workspace | boolean | true unless you have your own after_create hook | SI Fabrik clones the workspace and refreshes the base branch itself. |
git.base | string | the repository's current branch | Where task branches start and PRs target. |
git.save | boolean | true | Save the task branch into the project repository after every attempt and before cleanup. |
git.push | boolean | true with a git: block, else false | Push the branch to remote at hand-off. Forced on when a PR is requested. |
git.remote | string | origin | Remote to push to. |
git.pull_request | string or boolean | draft with a git: block, else off | draft, ready or off. true means draft. |
git.provider | string | detected from the remote URL | github, gitlab or none (push only). |
No git block, no pull requests
Without a git: block, branches are still saved into your repository, but nothing is pushed and no PR is opened. The wizard always writes a git: block.
limits#
Guardrails for this project. See Budgets and limits.
| Key | Type | Default | Description |
|---|---|---|---|
limits.daily_budget_usd | number | none | No new attempts or continuation turns once today's spend reaches this. Resets at local midnight. |
limits.daily_token_budget | integer | none | The same, in tokens. |
limits.max_cost_per_issue_usd | number | none | Park a task once its attempts together cost this much. |
limits.max_attempts_per_issue | integer | 5 | Park a task after this many failed attempts in a row. 0 retries forever. |
limits.pause_after_consecutive_failures | integer | 5 | Pause the project after this many failures in a row across all tasks. 0 never pauses. |
browser#
A headless Chromium with the Playwright MCP server in the sandbox. See Browser testing and previews.
| Key | Type | Default | Description |
|---|---|---|---|
browser.enabled | boolean | true if a browser: map exists | Give agents a browser. |
browser.viewport | string | 1280x800 | Window size, WIDTHxHEIGHT (each 200–4000). |
browser.device | string | A Playwright device name to emulate. | |
browser.image | string | harness-agent-browser:latest | Browser image, unless docker.image is set to something else. |
preview#
How to run the project's app in the sandbox.
| Key | Type | Default | Description |
|---|---|---|---|
preview.setup | string | Runs once per workspace before the app starts, for example npm ci. | |
preview.command | string | Starts the app, for example npm run dev -- -H 0.0.0.0. | |
preview.port | integer | Port the app listens on. Preview is on when command and port are both set. | |
preview.ready | string | / | Path that answers once the app is up. |
preview.ready_timeout_s | integer | 300 | How long to wait for it, 10 to 1800 seconds. |
links and sharing#
What this project uses from elsewhere, and who may use it. See Project links and Linked tasks.
| Key | Type | Default | Description |
|---|---|---|---|
links.packages[] | list | [] | Packages: name, from (registry, git or source), registry, url, project, ref, token_env, username (git, default oauth2). |
links.services[] | list | [] | Services: name, env, and either url (hosted) or project (run next to the agent) with optional ref and port. |
share_with | list | [] | Projects allowed to use this project's code and app. |
accept_tasks_from | list | [] | Projects whose agents may file linked tasks here. |
linked_tasks_state | string | Backlog | Where linked tasks land. An active state runs them without review. |
server#
| Key | Type | Default | Description |
|---|---|---|---|
server.port | integer | Informational only. The app-wide port is set in Settings → General. |