Skip to content

Instance Configuration

instance.yaml controls workflow and env-preset selection for a bot instance. It lives at <BOT_CONFIG_PATH>/agent/instance.yaml in the remote config repo.

Resolution Order

run.py resolves configuration in this order:

  1. instance.yaml, when present in the remote config repo.
  2. BOT_WORKFLOW_PRESET and BOT_ENV_PRESETS environment variables.
  3. Defaults: workflow jira-sprint, source jira, all available env presets.

The file is optional for default behavior. Use it when configuration must be explicit, reviewable, or different between profiles.

Reference

workflow: jira-sprint
source: jira
envs:
  - browser
  - slack
  - container-scan
claude_md:
  strategy: ignore
idle_cycle_limit: 0
Field Default Meaning
workflow jira-sprint Built-in workflow name or ./workflows/<name> for an instance workflow
source jira Work source passed to workflow skills
envs null null enables all env presets; [] disables them
claude_md.strategy ignore ignore, append, or replace for instance CLAUDE.md
idle_cycle_limit 0 Optional idle-cycle reminder threshold; 0 disables it

Environment Fallback

Use environment variables when no instance.yaml exists:

BOT_WORKFLOW_PRESET=jira-sprint
BOT_ENV_PRESETS=browser,slack,container-scan

An empty BOT_ENV_PRESETS value selects no env presets. Unknown workflow names are fatal at startup. Unknown env presets are logged and skipped.