Configuration Reference

Config Model

Tack merges config from three sources. Later layers override earlier ones:

Built-in defaults — embedded in the binary
User config — ~/.config/tack/config.yaml
Project config — <repo>/.tack/config.yaml

The daemon reads the user layer on startup. Project-scoped CLI commands read the merged result.

tack config list              # Show all merged values
tack config get models.default # Show a specific value

Complete Example

This example shows one possible Pi runtime with local sandboxes.

daemon:
  listen: "127.0.0.1:9800"
  external_url: ""
  data_dir: "~/.config/tack/data"
  base_branch: "main"

sandbox:
  provider: "local"
  worktree_dir: ""

project_setup:
  commands:
    - "bun install"
  verify:
    - "bun --version"

agents:
  runtime: "pi"
  max_concurrent: 8
  max_depth: 2
  stagger_delay_ms: 500
  idle_timeout_minutes: 15
  pi:
    provider: "openai-codex"
    model: ""
    thinking_level: "medium"
    extension_path: ""
  timeouts:
    default:
      max_duration_minutes: 30
      idle_minutes: 10
    planner:
      max_duration_minutes: 20
    builder:
      max_duration_minutes: 45
    reviewer:
      max_duration_minutes: 15

runtime_auth:
  mode: tack
  runtime: pi
  provider: openai-codex
  method: oauth
  credential_ref: openai-codex

models:
  default: gpt-5.4
  agent: gpt-5.4
  planner: gpt-5.4
  small_tasks: gpt-5.4-mini
  deterministic: gpt-5.4-mini

planning:
  default_mode: collaborative
  model: ""

watchdog:
  check_interval_seconds: 30
  nudge_after_minutes: 10
  escalate_after_nudges: 3

tools:
  max_per_agent: 20
  always_include: []
  always_exclude: []

git:
  author_name: Tack
  author_email: tack@local

quality_gates:
  - "bun test"
  - "bunx tsc --noEmit"
  - "bun run lint"

Field Reference

`daemon`

Field	Type	Default	Description
`listen`	string	`"127.0.0.1:9800"`	HTTP bind address for the daemon API and SSE events
`external_url`	string	`""`	Public URL for remote sandbox callbacks. Required when using Daytona sandboxes.
`data_dir`	string	`"~/.config/tack/data"`	Machine-wide runtime state directory. Stores SQLite databases and activity logs.
`base_branch`	string	`"main"`	Git branch used as the base for worktrees and merge target

`sandbox`

Field	Type	Default	Description
`provider`	string	`"local"`	Sandbox provider: `local` (git worktrees) or `daytona` (remote VMs)
`worktree_dir`	string	`""`	Override the directory where local worktrees are created. Empty uses the default location inside the repo.
`default_resources.cpu`	int	`2`	CPU cores allocated per Daytona sandbox
`default_resources.memory`	int	`2048`	Memory in MB allocated per Daytona sandbox
`default_resources.disk`	int	`10`	Disk in GB allocated per Daytona sandbox
`auto_stop_interval`	int	`30`	Minutes before idle Daytona sandboxes are auto-stopped
`auto_delete_interval`	int	`1440`	Minutes before stopped Daytona sandboxes are auto-deleted
`daytona.api_url`	string	`""`	Daytona API URL. If empty, uses the default Daytona endpoint.
`daytona.snapshot`	string	`""`	Daytona snapshot ID. Pre-built VM images with dependencies for faster startup.

sandbox.post_create exists as a deprecated compatibility input. Use project_setup.commands instead.

`project_setup`

Field	Type	Default	Description
`commands`	string[]	`[]`	Shell commands to run after sandbox creation (e.g., `"bun install"`)
`verify`	string[]	`[]`	Lightweight checks to confirm setup succeeded (e.g., `"bun --version"`)

`agents`

Field	Type	Default	Description
`runtime`	string	`"pi"`	Agent runtime. Supported values include `pi` and `claude-code`. See Agent Runtimes.
`max_concurrent`	int	`8`	Maximum number of agent sessions running at the same time
`max_depth`	int	`2`	Maximum nesting depth for blueprint references
`stagger_delay_ms`	int	`500`	Milliseconds to wait between spawning concurrent agents
`idle_timeout_minutes`	int	`15`	Coarse idle timeout. Overridden by per-role `timeouts` if set.
`pi.provider`	string	`"anthropic"`	LLM provider for the Pi runtime.
`pi.model`	string	`""`	Model override for Pi. If empty, uses `models.default`.
`pi.thinking_level`	string	`"medium"`	Pi thinking level: controls how much reasoning the model does
`pi.extension_path`	string	`""`	Path to custom Pi extension directory. If empty, uses the embedded extension.

Per-role timeout configuration. Each role can have max_duration_minutes (total wall clock) and idle_minutes (time since last output). The top-level idle_timeout_minutes is the coarse default; per-role idle_minutes overrides it when set.

Role	Default `max_duration_minutes`	Default `idle_minutes`
`default`	30	10
`planner`	20	— (inherits default)
`builder`	45	— (inherits default)
`reviewer`	15	— (inherits default)

`runtime_auth`

Controls how credentials get from Tack's credential store into the running agent.

Field	Type	Default	Description
`mode`	string	`"tack"`	`tack` (Tack manages and injects credentials) or `native` (runtime uses its own auth)
`runtime`	string	—	Runtime name this auth config applies to
`provider`	string	—	LLM provider this auth config applies to
`method`	string	`"api_key"`	Authentication method: `api_key` or `oauth`
`credential_ref`	string	—	Key in the credentials store to read from. Required when `mode: tack`.

`models`

Model selection split by purpose. Each field accepts a model identifier string.

Field	Description
`default`	Fallback for any role not explicitly set
`agent`	Builder and reviewer agents
`planner`	Planner agent
`small_tasks`	Lightweight operations where a smaller model suffices
`deterministic`	Deterministic step operations

`planning`

Field	Type	Default	Description
`default_mode`	string	`"collaborative"`	Planning mode. Currently only `collaborative` is supported.
`model`	string	`""`	Shared planning model override. If empty, uses `models.planner`.

`watchdog`

Monitors agent health and triggers escalation when agents stall.

Field	Type	Default	Description
`check_interval_seconds`	int	`30`	How often the watchdog checks agent status
`nudge_after_minutes`	int	`10`	Minutes of inactivity before sending a nudge to the agent
`escalate_after_nudges`	int	`3`	Number of nudges before escalating to human

`tools`

Controls agent tool access globally. Also configurable per-blueprint-step and per-rule.

Field	Type	Default	Description
`max_per_agent`	int	`20`	Maximum number of tools available to each agent
`always_include`	string[]	`[]`	Tools that are always available regardless of other restrictions
`always_exclude`	string[]	`[]`	Tools that are always removed from agent tool sets

`git`

Field	Type	Default	Description
`author_name`	string	`"Tack"`	Author name for commits made by agents
`author_email`	string	`"tack@local"`	Author email for commits made by agents

`quality_gates`

List of shell commands. Each command runs in the sandbox. Non-zero exit means failure. Examples:

JavaScript/TypeScript:

quality_gates:
  - "bun test"
  - "bunx tsc --noEmit"
  - "bun run lint"

Go:

quality_gates:
  - "go vet ./..."
  - "go test ./..."
  - "go build ./..."

Override in .tack/config.yaml when your project needs different validation commands.

Credentials

Stored separately in ~/.config/tack/credentials.yaml:

providers:
  openai-codex:
    type: oauth
    access_token: "..."
    refresh_token: "..."
    expires_at: 0

git:
  type: pat
  host: github.com
  token: GITHUB_TOKEN

sandbox:
  daytona:
    type: api_key
    api_key: DAYTONA_API_KEY

Credential values can be:

Literal secrets — stored directly in the file
Environment variable names — Tack reads os.Getenv() for the value
Shell command lookups — !op read op://vault/item runs the command and uses the output

See the Credentials & Auth guide for full details.

Environment Variables

Common environment variables used by credential references:

Variable	Purpose
`ANTHROPIC_API_KEY`	Anthropic API authentication
`OPENAI_API_KEY`	OpenAI API authentication
`GITHUB_TOKEN`	GitHub PAT for PR creation and repo access
`DAYTONA_API_KEY`	Daytona sandbox API authentication