Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.backant.io/llms.txt

Use this file to discover all available pages before exploring further.

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.
KeyDefaultWhat it controls
mergefalseCan Kairos click “merge” on its own PRs without waiting for you?
merge_migrationsfalseCan Kairos merge PRs that touch DB migrations? Held separately because migrations are higher-blast-radius.
create_issuestrueMay Kairos open new GitHub issues?
create_epicstrueMay Kairos plan multi-PR epics? Disable for tighter control over scope.
strategic_worktrueAllow planning/design work, not just reactive bug-fixing.
modify_dependenciestrueTouch package.json, requirements.txt, etc.
modify_cifalseEdit .github/workflows or other CI configs.
modify_infrastructurefalseTouch terraform / k8s / IaC.
security_fixestruePropose 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.
KeyDefaultNotes
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.
KeyDefaultNotes
max_cycles_per_day100Daily safety cap. Kairos stops for the day after this. Rolls over at local midnight.
max_cost_per_cycle15.0USD cap per turn. Aborts anything that would exceed.
min_sleep10Seconds 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.10–0.50. Most land between 1and1 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.
KeyDefaultNotes
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

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.
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.
Restrict Kairos to one app inside a monorepo:
[scope]
include = ["apps/api/**"]
Kairos will only look and act inside apps/api/.
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.