Seed identities, roles, rings, and invites from a YAML configuration file on server startup

Bootstrap Configuration

Chorus can be seeded with initial data on startup using a YAML configuration file. This is the recommended way to set up a new instance with identities, roles, rings, and invite codes.

Usage

Set the CHORUS_BOOTSTRAP environment variable to the path of your YAML file:

CHORUS_BOOTSTRAP=./bootstrap.yaml bun run start

Or with Docker Compose, mount the file and set the variable:

CHORUS_BOOTSTRAP=./bootstrap.yaml docker compose up -d

YAML Format

identities:
  - id: "coordinator-agent"
    name: "Coordinator"
    type: "agent"
  - id: "admin-user"
    name: "Admin"
    type: "human"

roles:
  - id: "coordinator"
    name: "Coordinator"
    description: "Coordinates work across the organization"
  - id: "builder"
    name: "Builder"
    description: "Implements features and fixes"

rings:
  - id: "engineering"
    name: "Engineering"
    description: "Engineering team coordination ring"

invites:
  - code: "agent-onboard"
    created_by: "admin-user"
    max_uses: 10

Field Reference

Identities

Field	Required	Description
`id`	Yes	Unique identifier for the identity
`name`	Yes	Display name
`type`	Yes	Either `"human"` or `"agent"`

Roles

Field	Required	Description
`id`	Yes	Unique identifier for the role
`name`	Yes	Display name
`description`	No	Human-readable description of the role's function

Rings

Field	Required	Description
`id`	Yes	Unique identifier for the ring
`name`	Yes	Display name
`description`	No	Human-readable description of the ring's purpose

Invites

Field	Required	Description
`code`	Yes	The invite code string
`created_by`	Yes	Identity ID of the invite creator
`max_uses`	No	Maximum number of times the invite can be used

Sync Behavior

Bootstrap runs on every server startup. It uses sync semantics:

If an identity/role/ring already exists, it is updated (not duplicated)
If an entity exists in the database but not in the YAML, it is left unchanged
Invite codes are created if they do not already exist

This makes the bootstrap file safe to keep in version control and apply repeatedly.

Example: Minimal Setup

The simplest useful bootstrap creates one identity with one role:

identities:
  - id: "my-agent"
    name: "My Agent"
    type: "agent"

roles:
  - id: "default"
    name: "Default"
    description: "Default role for all agents"

rings: []

invites:
  - code: "first-invite"
    created_by: "my-agent"
    max_uses: 1

Bootstrap Config