/ 
App-karr-0.600
/ karr-foundation

NAME

karr-foundation - Single-shot foundation daemon for periodic karr agent execution

VERSION

version 0.600

SYNOPSIS

# Every 5 minutes via cron
*/5 * * * * karr-foundation

# One-shot run forcing execution in all repos
karr-foundation --force

# Preview without executing
karr-foundation --dry-run --verbose

# Ask the fleet a question, and answer it from anywhere
karr-foundation ask "Which registry?" --options cpan,darkpan --wait 3600
karr-foundation answer 7 darkpan

# Write the fleet's plan into the hub, and execute it out of there
karr-foundation plan < chain.yml
karr-foundation chain

DESCRIPTION

karr-foundation reads a config file listing karr board directories, detects board changes or open tasks, and invokes a configured agent command for each active repo. It is designed to be called repeatedly -- by cron, a systemd timer, or a tight while-loop.

See App::karr::Foundation for full documentation.

EXIT CODES

Cron only ever asked whether the tick failed, but the mailbox commands are typed by a person and scripted by agents, so karr-foundation keeps the same exit-code contract as karr (see docs/adr/0002-exit-code-contract.md):

  • 0 -- the tick finished: boards were drained, an overview was printed, a question was asked or answered, a chain was written, or the chain was worked through. A chain step that failed does not change this: that is a statement about the plan, not about this binary.

  • 1 -- runtime failure: no repository could be discovered, the config file does not parse or is not a mapping, a hub command found no hub, ask rejects a value it accepted syntactically as the wrong string (an unrecognized --policy, a --default not among --options, a policy that needs a --deadline it was not given), the question being answered already had an answer, the chain document handed to plan is not a chain, or chain could not fetch refs/karr-foundation/* and refused to run a step another machine may already be running.

  • 2 -- usage error: an unknown command, an unknown option, an option value MooX::Options itself rejects by type (--wait takes an integer), or a missing or surplus positional argument. A value MooX::Options accepts as a plain string but a command then rejects on its own terms -- see 1 above -- is a runtime failure, not this.

A run killed by SIGTERM, SIGINT or SIGHUP exits 128 + signal after taking its agents down with it, the usual shell convention for signal death.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/karr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)