Configuration Reference

The user-facing Configuration page covers loading order and a worked tack.toml example. This page is the book's rendering of the complete, authoritative TACK_* variable table — server, embedded runner, standalone runner, backup, orchestration, and the execution domain. Edit docs/CONFIG.md, not this file.

Configuration Reference

The complete environment/TOML configuration for the API server and the runner. Moved from CLAUDE.md (2026-08-19) so agent context stays lean; this file is the single authority for these tables — update it, not CLAUDE.md, when adding a variable.

The API server loads configuration from tack.toml (if present) or environment variables:

The tack CLI client — every subcommand other than serve — talks to a running server over HTTP and never opens the database. It resolves the server's base URL from --base-url, then TACK_API_URL, then ~/.tackrc, then http://127.0.0.1:3210.

The tack-runner binary is configured separately (defaults → TOML → environment → CLI flags, in that order):

Runner credentials are redacted in every log, Debug impl and error — the redaction is structural (RunnerCredential's Debug/Display are hardcoded to [REDACTED]), not convention.

The TACK_BACKUP_* values are defaults. Cloud-backup settings (endpoint, bucket, region, access/secret key, prefix, retention) can also be edited at runtime from the UI (Settings → Cloud Backup) and are stored in the app_meta table; UI values override the env defaults. TACK_BACKUP_INTERVAL_SECS (automatic scheduling) remains env-only and takes effect at startup. The secret key is write-only over the API — never returned to clients.

Embedded runner (tack serve --with-runner)

tack serve --with-runner (or TACK_LOCAL_RUNNER_ENABLE=1) runs the runner role as a task inside the same process as the server, speaking runner-v1 over loopback HTTP exactly like a remote runner would — see docs/adr/0058-standalone-single-binary-runner.md for why that HTTP hop is kept rather than shortcut. This is the fewest-steps way to see a real agent attempt run against your own board: no second binary, no tack runner enroll call, no token to copy anywhere.

• Gate. Off by default. TACK_LOCAL_RUNNER_ENABLE (table above) and --with-runner are equivalent; either turns it on. Refused outright — before any socket or database is opened — when the server is not bound to loopback (TACK_HOST other than 127.0.0.1/localhost/an equivalent loopback address); this is a startup error, never a silent downgrade to a runner-less server, because an embedded runner executes arbitrary coding-agent processes on the host serving the UI.

• UI toggle (ADR 0061 decisions 2 and 6). GET/PUT /api/local-runner let a loopback-only UI turn the embedded runner on/off after tack serve is already up, with no restart — a PUT persists the choice to app_meta (overriding TACK_LOCAL_RUNNER_ENABLE from then on) and starts or stops the runner task to match. PUT/GET/DELETE /api/local-runner/secrets(/{name}) hand the runner a provider key the same way — write-only, never echoed, stored in whichever backend tack runner secret set would have used. Every one of these routes is absent (a plain 404, not a gate that refuses) on any non-loopback bind, or when the process embedding the server never wired an embedded runner in at all (a bare library caller of tack_api::serve()).

• First run. A fresh state directory with no stored session self-provisions: it creates its own pending-runner row and redeems its own one-time enrollment token in-process, so no token is ever printed, copied, or configured by hand. A later start against the same state directory reuses the credential already on disk instead of provisioning a second runner.

• State directory. Defaults to <TACK_STORAGE_DIR>/runner — scoped to the same configuration as the database, so a server started against a different TACK_DATABASE_URL (paired, as every other per-install artifact in this crate already assumes, with its own TACK_STORAGE_DIR) never resolves to another server's runner state. TACK_RUNNER_STATE_DIR still overrides this default when set, exactly as it does for the standalone tack-runner binary (whose own default remains the bare, cwd-relative .tack-runner — it has no database or storage_dir to scope against). Holds the runner's credential (session.json) and its attempt journal, both written owner-only (session.json mode 0600; the directory itself and journal entries 0700/0600) — confirmed with stat -c '%a' against a real run, not assumed from the write path. An install upgrading from before this default existed has its already- enrolled state moved there automatically, once, the first time the new directory is found missing and the old one is not — never the reverse, and never once the new directory already exists.

• Vendor/provider credentials — Tack is never a model gateway. Each harness authenticates itself using its own mechanism; Tack does not read, store, forward, or proxy any of it, embedded or standalone. tack runner doctor reports exactly what this machine's own harnesses declare — run it yourself rather than trusting a stale copy in this file. The two harnesses with a login of their own, mirrored from a real tack runner doctor run on a machine with both installed — the harness vocabulary itself is open (a runner may report any kind string); docket and opencode always need a configured endpoint and are described in the book's Choosing a harness:

  Harness	How it authenticates	Gateway-routed variant ([provider.vercel_ai_gateway])
  codex	Its own CLI login flow or an API key it reads from its own environment/config (codex --help). This adapter forwards no ambient host environment into a run — only entries explicitly set on the execution request's own environment field ever reach the process.	When a request's provider names the configured endpoint: per-invocation -c model_provider=…/model_providers.<key>.* flags plus AI_GATEWAY_API_KEY in the spawned environment — never a write to ~/.codex/config.toml. A request for a direct model receives none of it.
  claude-code	Typically an OAuth session under $HOME/.claude from its own login flow, or an API key from its own environment. This adapter forwards HOME and PATH from the runner process's own environment so the installed CLI can find its existing session.	ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN (plus a defensive empty ANTHROPIC_API_KEY) in the spawned environment, only when the request's provider names the configured endpoint. A request for a direct model receives none of it.

  OpenRouter access and local-model endpoints (llama.cpp and similar) are configured the same way: through the harness's own configuration or environment. No TACK_* variable on the API server names a model provider or endpoint, and the API server itself never holds, forwards, or proxies a provider credential. The runner is not under that restriction: it may hold a provider key in its own owner-only state directory, and a loopback-only, embedded-runner-only route hands one to that store without the key ever touching tack.db, a log line, or the operator API otherwise — see docs/adr/0061-provider-credentials-at-the-runner-boundary.md for what a runner may hold, how a key reaches it, and how a gateway's model catalog is fetched. See docs/adr/0050-runner-control-plane.md ("the Tack API never starts a coding harness and never becomes a model proxy") and docs/adr/0058-standalone-single-binary-runner.md ("Vendor credentials remain outside Tack") for the decisions this one bounds.

• Model selection is a separate question from credentials, and it is answered. Which (provider, model_id) reaches the harness for a given execution request is resolved server-side through a four-tier precedence (request override → agent-profile default → project default (projects.default_model, set from the Agents page or PATCH /api/projects/{id}) → fleet default → auto-select), live-verified end to end and fully documented in Choosing a model and a provider — including why an auto-select request accepts today but never schedules. No TACK_* variable is involved on either side of this: routing the choice and holding the credential are different operations, and this file's table above has no row for a model provider or endpoint by design.

• Log visibility. The embedded runner's own log lines (self-provisioning, enrollment, claim, completion — anything logged by tack_runner::* or by the tack binary's own local_runner/local_enrollment modules) do not appear under default logging. init_tracing's default filter (tack_api={level},tack_db={level},tack_core={level},tower_http=debug) only ever names tack_api, tack_db and tack_core — TACK_LOG_LEVEL changes {level} for those three crates but cannot add a target the filter string never mentions, so this is not fixable by raising TACK_LOG_LEVEL alone. Set RUST_LOG explicitly to include the runner's own targets:

  RUST_LOG=tack=info,tack_runner=info,tack_api=info,tack_db=info,tack_core=info \
    tack serve --with-runner
  

  Verified on a fresh state directory: under default logging, tack_runner::* and tack::local_enrollment/tack::local_runner produced zero log lines while the embedded runner enrolled and ran a real attempt; with the RUST_LOG override above, the same run showed tack::local_enrollment: self-provisioned a local runner for the embedded runner to redeem ..., tack_runner::runtime: runner runtime started ... and tack_runner::client::transport: runner enrolled .... Server-side handler logs (e.g. tack_api::handlers::runner_protocol's own runner enrolled runner_id=... line) are visible either way, since tack_api is already in the default filter — only the runner's own log lines were missing.

Runner verifier ([verify])

A runner can run a program of your choosing over each attempt that succeeded, after the attempt's changes are captured and before its workspace is deleted. The program reads the captured evidence and writes a merge-readiness pack; the runner uploads that pack as one more artifact on the attempt. The runner runs it, on your machine: the board never runs it.

[verify]
enabled = false          # off by default; there is no environment variable for it
program = "assay"        # looked up on PATH
args = ["verify"]        # placed before the flags the runner adds
timeout_seconds = 1800

The runner appends --evidence <dir> --workspace <dir> --output <dir>/mrp.json to args and starts the program with an environment of PATH only. A program that exits non-zero, times out, is not on PATH, or writes a pack that does not parse never changes the attempt's outcome: the attempt still completes succeeded and records an attempt.verify_failed event carrying the exit code and the start of the program's error output. With enabled = false, nothing is started. A run request can decline the verifier for one run (the run dialog's "Verify the result" box); it can never turn on a verifier the runner has off. A request that asks for one from a runner without it changes nothing, and the attempt records an attempt.verify_skipped event saying why. A program that is not on PATH is logged as a warning when the runner starts.

Pushing the attempt's branch ([git])

A runner can push the work of each succeeded attempt to the remote it fetched the repository from, so the result is a branch you can open, review and merge. The runner pushes it, on your machine, with your git credentials (your credential helper or SSH agent): Tack stores no git credential, and the board never pushes.

[git]
push_branches = false    # off by default; there is no environment variable for it
branch_prefix = "tack/"
author = "Tack Runner <tack-runner@localhost>"

When push_branches = true and an attempt succeeded with a non-empty change, the runner creates the branch <branch_prefix><item short id>-a<attempt number>, commits what the harness left uncommitted (with author as the commit author; the message names the attempt and the item, never the item's description) and runs git push origin <branch>. Git hooks in the workspace do not run. The branch, its head commit and whether it was pushed are recorded in the attempt's evidence and its completion report. A push that fails (no credentials, a rejected branch, an unreachable remote) never changes the attempt's outcome: the attempt still completes succeeded and records an attempt.push_failed event. With push_branches = false, nothing is committed or pushed.

Turn it on only for agents you would trust with your git credentials. The push runs git in the attempt's workspace, which the agent could write to while it worked: hooks are disabled, but the repository's own git configuration there (an SSH command or a URL rewrite, for example) is whatever the agent left.

As with the verifier, a run request can decline the push for one run but never enable it; asking for a push from a runner with push_branches = false changes nothing and the attempt records an attempt.push_skipped event.

Debugging

# Debug logging
TACK_LOG_LEVEL=debug cargo run -p tack-cli -- serve

# Trace SQL queries
RUST_LOG=tack_db=trace,tack_api=debug cargo run -p tack-cli -- serve

# JSON logs (for log aggregators)
TACK_LOG_JSON=true cargo run -p tack-cli -- serve

# See the embedded runner's own log lines under `--with-runner` (see
# "Embedded runner" above — off by default, silent by default)
RUST_LOG=tack=info,tack_runner=info,tack_api=info,tack_db=info,tack_core=info \
  cargo run -p tack-cli -- serve --with-runner