Automations and agents
killBottleneck automates on two levels: templates create recurring projects by themselves, and AI agents perform individual steps of a map — an n8n workflow, a cron job, whatever answers a webhook.
In-map automation without agents
"When X → do Y" directly in the map is handled by automation rules — including deputies and dynamic targets.
Recurring templates
Any map can be saved as a template — personal, or for the whole organization, optionally including its tasks. Deadlines are stored as "days from start" and recalculated when the template is used.
A template can also create projects automatically: every week on a chosen weekday, or on the N-th (or last) day of the month, in the morning. The hour and time zone are configurable (KB_AUTO_HOUR, TZ — see Configuration); if the server was off at that hour, the project is created later the same day, not skipped.
Numbered series: a template can number the projects it creates — "Payroll 2026-1", "Payroll 2026-2"… A new year starts a new series from 1, and a custom name given at creation gets its number too. The archive keeps a series together, ordered by number.
Who performs a step
Every goal records whether a person or an automation performs it. The responsible person is always a human — even for an automated step someone is accountable, gets the notifications and sees the goal in their My day. On any goal you can also tick "I would like this automated": the request goes to the AI managers (a flag on a user, independent of their role), and once the automation is built and recorded on the goal, the request tidies itself away and you get a notification.
The AI agent registry
An AI manager (or an administrator) maintains the directory of automations: name, webhook address, signing secret, enabled/disabled, and optionally who may run it (a list of e-mails; empty = anyone who can edit a map). On a goal the automation is picked by name — team members never see the address or the secret.
When an automation runs
An automated goal does not start by itself when created — it waits for one of these:
- You switch the goal to In progress. The manual "doing it now" — starts the automation immediately. It's also how a failed run is retried (switch back to In progress).
- The goal's "turn comes" — all of its subgoals get completed. You must turn on the "waits for subtree" toggle on the goal for this dependency behaviour; without it the goal does not wait for its subgoals.
- You attach a file to the goal — the file kicks off processing.
The run's state (pending / running / done / failed, with the reason on failure) is visible right in the goal's dialog. When the agent reports done, the goal completes and the next step is unblocked — automated steps chain themselves. A run that never reports back is failed by a watchdog after a timeout (KB_AGENT_TIMEOUT_MIN, default 90 minutes) and both the responsible person and the AI managers are told.
The name must match a registered agent
If you name an automation that matches no registered, enabled agent (say the name of an agent you still intend to create, or an external process outside killBottleneck), the step simply doesn't run — it's treated as a note "a machine does this", not as an instruction. No failure notification is sent. To just pencil in an automation for later, use the goal's "I'd like this automated" toggle — it tells the AI managers to build it.
Two variables worth knowing about
KB_PUBLIC_URL tells the agent where to report back — without it a remote agent ends up calling itself. And agents on a private network (a typical self-hosted n8n) need KB_ALLOW_PRIVATE_WEBHOOKS=1. Details in Environment variables → Automations.
Driving killBottleneck from outside: API keys and MCP
The other direction — your code or your AI assistant working the maps — goes through API keys (user menu → API keys). A key has a scope (Read only or Read and write), an optional expiry, and the token is shown exactly once. It opens two doors:
- the REST API for scripts and integrations,
- the built-in MCP server for AI assistants such as Claude — "make a map out of these meeting notes", bulk edits, ticking off what is done.
A key reaches its owner's maps and tasks, never administration, AI settings or users; a whole map cannot be deleted through the API, and neither can the apex.
Next
- MCP server — connecting an AI assistant step by step
- Environment variables — the automation-related configuration