Configuration

backant setup generates a .backant.toml at the root of each project. This file is the only place Kairos’s per-project behaviour lives. It is committed to your repo and added to CODEOWNERS during setup so policy changes route to you for review. You can edit it by hand, or change keys through the CLI, which validates the value, rewrites the file, and records who changed what:

backant ctl config status --json                 # every key with value, default, and whether it was answered
backant ctl config set permissions.merge true    # one key; takes effect on the next turn
backant ctl config get behavior.max_cost_per_cycle --json
backant ctl config schema --json                 # the full contract: type, default, question, why

A host agent uses the same verbs to interview you key by key; see Let your agent run Kairos.

ctl config set rewrites the whole file from the contract. Hand-written comments and unknown keys are dropped and reported in the envelope’s dropped list.

Default `.backant.toml`

[permissions]
merge = false
merge_migrations = false
create_issues = true
create_epics = true
strategic_work = true
modify_dependencies = true
modify_ci = false
modify_infrastructure = false
security_fixes = true

[scope]
include = []
exclude = [".github/workflows/**", "terraform/**", "*.tfvars"]

[behavior]
max_cycles_per_day = 100
max_cost_per_cycle = 15.0
min_sleep = 10
deploy_verification = "full"

[branches]
target = "main"
prefix = "kairos/"

[freshness_manager]
enabled = true
cadence_cycles = 3
model = "claude-sonnet-4-6"

[dream_tools]
enabled = true
model = "claude-sonnet-4-6"

[gates]
actions = ["git_push", "pr_create"]
timeout_minutes = 60
timeout_policy = "requeue"

`[permissions]`

What Kairos is allowed to do.

Key	Default	What it controls
`merge`	`false`	Can Kairos click “merge” on its own PRs without waiting for you?
`merge_migrations`	`false`	Can Kairos merge PRs that touch DB migrations? Held separately because migrations are higher-blast-radius.
`create_issues`	`true`	May Kairos open new GitHub issues?
`create_epics`	`true`	May Kairos plan multi-PR epics? Disable for tighter control over scope.
`strategic_work`	`true`	Allow planning/design work, not just reactive bug-fixing.
`modify_dependencies`	`true`	Touch `package.json`, `requirements.txt`, etc.
`modify_ci`	`false`	Edit `.github/workflows` or other CI configs.
`modify_infrastructure`	`false`	Touch terraform / k8s / IaC.
`security_fixes`	`true`	Propose patches when CVEs or insecure patterns are detected.

Leave merge = false until you’ve built trust with Kairos on your codebase. PRs will sit waiting for your approval — which is what you want during the first week or two.

`[scope]`

Where Kairos is allowed to look and edit.

Key	Default	Notes
`include`	`[]`	Glob allow-list. Empty means “everything not excluded”.
`exclude`	`[".github/workflows/", "terraform/", "*.tfvars"]`	Always off-limits. Match against repo-relative paths.

If you set include, only those paths are visible to Kairos. Useful for monorepos where you want Kairos focused on one app.

[scope]
include = ["packages/api/**", "packages/shared/**"]
exclude = [".github/workflows/**", "infra/**"]

`[behavior]`

Safety caps and pacing.

Key	Default	Notes
`max_cycles_per_day`	`100`	Daily safety cap. Kairos stops for the day after this. Rolls over at local midnight.
`max_cost_per_cycle`	`15.0`	USD cap per turn. Aborts anything that would exceed.
`min_sleep`	`10`	Seconds between turns. Overridden by `--turbo` and `--pace` flags on `backant start`.
`deploy_verification`	`"full"`	After a merge to the target branch: `"full"` waits for the deploy workflow, the rollout, and a health check; `"workflow_only"` waits for the workflow only; `"disabled"` moves on right after the merge.

The cheapest turn on a small repo is roughly

0.10–

0.50. Most land between

1 and

5. max_cost_per_cycle = 15.0 is generous; if you’re seeing high bills, lower it to 5.0 and inspect with backant eval run.

`[branches]`

PR strategy.

Key	Default	Notes
`target`	`"main"`	Base branch for Kairos-created PRs.
`prefix`	`"kairos/"`	Branch prefix. Helps you filter Kairos’s work from your own.

`[gates]`

Actions that always wait for a human yes, even when a permission would allow them.

Key	Default	Notes
`actions`	`["git_push", "pr_create"]`	Action classes that park as a gate. Answer with `backant ctl gate answer <id> --approve` or `--deny --reason ...`. Empty list: nothing waits.
`timeout_minutes`	`60`	How long a gate may wait for an answer.
`timeout_policy`	`"requeue"`	`"requeue"` brings the action back as a new gate on a later turn; `"auto_deny"` drops it and records a denial.

`[freshness_manager]`

A small helper that periodically re-checks that memory still matches the repo.

Key	Default	Notes
`enabled`	`true`	Turn the helper off to save the extra calls.
`cadence_cycles`	`3`	Main turns between freshness checks.
`model`	`"claude-sonnet-4-6"`	Model id for the check.

`[dream_tools]`

Offline memory consolidation. See Dream pass.

Key	Default	Notes
`enabled`	`true`	Whether dream passes run when sleep pressure builds.
`model`	`"claude-sonnet-4-6"`	Model id for dream passes.

Reloading policy

Edits to .backant.toml take effect on the next turn. The daemon rebuilds its permissions block from the file before every turn, so no restart is needed.

Common adjustments

Building trust gradually

Week 1: defaults (merge = false, modify_ci = false, modify_infrastructure = false).Week 2–3: review Kairos’s PRs daily; if they look clean, consider flipping merge = true on quiet evenings only.Week 4+: if you want it, merge = true plus modify_ci = true for non-critical CI changes. Keep modify_infrastructure = false indefinitely unless you have strong out-of-band gates.

Reducing the cost ceiling

If a single turn is more expensive than expected:

[behavior]
max_cost_per_cycle = 5.0

Combine with backant start --pace so Kairos auto-throttles when your Anthropic rate-limit window heats up.

Monorepo focus

Restrict Kairos to one app inside a monorepo:

[scope]
include = ["apps/api/**"]

Kairos will only look and act inside apps/api/.

Strict read-only mode

Useful while evaluating Kairos against a sensitive repo. Kairos will still observe and judge, but will not write code:

[permissions]
merge = false
create_issues = false
create_epics = false
strategic_work = false
modify_dependencies = false
modify_ci = false
modify_infrastructure = false
security_fixes = false

Effectively reduces Kairos to a backant watch-only product.

Where `.backant.toml` lives

At the root of each workspace, alongside your code. It’s a normal committed file; Kairos enforces the policy on every turn. Setup auto-adds an entry to .github/CODEOWNERS for .backant.toml so the file is review-gated.

Get started

Daily operation

Commands

Reference

Default `.backant.toml`

`[permissions]`

`[scope]`

`[behavior]`

`[branches]`

`[gates]`

`[freshness_manager]`

`[dream_tools]`

Reloading policy

Common adjustments

Where `.backant.toml` lives

​Default .backant.toml

​[permissions]

​[scope]

​[behavior]

​[branches]

​[gates]

​[freshness_manager]

​[dream_tools]

​Reloading policy

​Common adjustments

​Where .backant.toml lives

Default `.backant.toml`

`[permissions]`

`[scope]`

`[behavior]`

`[branches]`

`[gates]`

`[freshness_manager]`

`[dream_tools]`

Reloading policy

Common adjustments

Where `.backant.toml` lives