Robot Repository Layout

The robot’s writable home directory is where you launch the engine. The important subdirectory inside it is usually custom/.

Typical robot home

acme-bot/
  .env
  .setup-state
  custom/
    conf/
      robot.yaml
      environments/
      protocols/
      brains/
      history/
      plugins/
      jobs/
    plugins/
    jobs/
    tasks/
    lib/
  workspace/

What lives where

• .env: deployment-specific environment variables and secrets
• custom/conf/robot.yaml: robot-wide policy and environment include point
• custom/conf/environments/*.yaml: environment-specific runtime defaults
• custom/conf/protocols/*.yaml: connector-local ProtocolConfig
• custom/conf/brains/*.yaml: selected brain provider settings
• custom/conf/history/*.yaml: selected history provider settings
• custom/conf/plugins/*.yaml: plugin matchers, help, and local config
• custom/conf/jobs/*.yaml: job schedules and local job config
• custom/plugins/, custom/jobs/, custom/tasks/: your automation code
• custom/lib/: shared helper code for external languages
• workspace/: working files generated by jobs or tasks

Installed defaults versus custom files

Gopherbot always loads installed defaults first and then overlays your custom files on top. That means your custom robot should usually contain only the local delta:

• enable or disable shipped features
• provide secrets and parameters
• add new plugins, jobs, or tasks
• intentionally override behavior

Avoid copying the engine’s whole default config into custom/ unless you truly want to fork that behavior.