Configuration - BackAnt

backant setup generates a .backant.toml at the root of each project. This file is the only place you change Kairos’s per-project behaviour. The file is committed to your repo and added to CODEOWNERS during setup so policy changes route to you for review.

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/"

`[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"`	`"full"` enforces the deploy-verification gate; `"fast"` skips slow checks; `"off"` disables.

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.

Reloading policy

Edits to .backant.toml are not picked up by a running daemon. Restart with --fresh so the new policy is applied immediately:

backant stop
backant start --fresh

The reset is hard but bounded — only in-process judgment is dropped. Memory, lessons, learnings, dream state, and eval reports are preserved.

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.

​Default .backant.toml

​[permissions]

​[scope]

​[behavior]

​[branches]

​Reloading policy

​Common adjustments

​Where .backant.toml lives

Default `.backant.toml`

`[permissions]`

`[scope]`

`[behavior]`

`[branches]`

Reloading policy

Common adjustments

Where `.backant.toml` lives