references/bot-development.md
GitHubOC2 Bot Model
Discovery and Execution
The bot engine loads BaseBot subclasses from Python files under shared/bots/on. It skips any class whose name starts with Base. It receives OC2 events and calls the corresponding handler. Changes require a bot-engine container restart.
Bots run outside the API's database transaction. Mutating an Implant or BaseTask received by a handler changes only that in-memory object; use an OC2 service for persistent effects.
Bot instance fields survive between callbacks in one process, but are lost on restart and are not shared across replicas.
Reliability
- Filter before taking action.
- Design for repeated events when practical.
- Keep network work bounded and avoid scheduling loops.
- Catch expected integration failures close to the failing call.
- Add dependencies to
bot_engine/requirements.txtand rebuild the image; do not install them at runtime.
Troubleshooting
Check that:
- the file is under
shared/bots/on; - the class derives from
BaseBot; - a custom constructor calls
super().__init__(); - imports and dependencies succeed;
- the bot engine was restarted;
- logs show module loading and no handler exception.