Configuration reference

Wheems is configured with YAML and Markdown files in your install folder. This page lists every key Wheems 0.0.3 accepts, taken from its schemas, with its type, default and an example. Keys that are accepted but not used yet are marked Planned.

• Keys are snake_case.
• Names of workspaces, agents, accounts, connections, channels, skills and workflows are lowercase letters, digits and dashes, starting with a letter or digit, at most 64 characters: acme, chief-of-staff, weekly-report.
• Unknown keys are errors, so a typo never passes silently.
• Links between files are checked: a workspace may only use the install’s accounts and connections, an agent only its workspace’s accounts and skills, and pinned skill versions must exist in the library.

Check everything, with line numbers:

wheems validate                                   # the whole install
wheems validate workspaces/acme/workspace.yaml    # one file

Valid

A problem is reported with its file and line:

workspaces/acme/workspace.yaml:3: error Unrecognized key: "chanels"
1 error

The service refuses to start while there are errors. Restart it after any change: wheems service restart.

Every format has a JSON Schema, shipped in the package’s schemas/ folder: install.schema.json, workspace.schema.json, agent.schema.json, skills.schema.json and workflow.schema.json. Point an editor with the YAML language server at one for completion and hover help:

# yaml-language-server: $schema=/opt/homebrew/lib/node_modules/wheems/schemas/workspace.schema.json
name: Acme

npm root -g prints where global packages live, if yours differs.

~/wheems/                       your install: a git folder
├── install.yaml                accounts, connections, machines, knowledge settings
├── about-you.md                every agent in every workspace reads it
├── library/skills/             every version of every skill
├── workspaces/<id>/
│   ├── workspace.yaml
│   ├── agents/<name>.md
│   ├── skills.yaml
│   ├── knowledge/
│   ├── CLAUDE.md, AGENTS.md    written at each launch; ignored by git
│   └── workflows/<name>.yaml   planned
└── .wheems/                    running state, never committed
    ├── conversations.json      which thread is which session
    ├── wheems.sock             the control socket
    ├── slack-app-manifest.yaml
    ├── logs/service.log
    ├── bin/wheems              the command agents run
    ├── index/                  search indexes
    ├── filing/, tidy/          the filer's working copies
    ├── review/                 skill proposals and about-you suggestions
    └── quarantine/             notes that looked like they held a credential
~/.config/wheems/secrets.json   tokens, readable only by you

What every workspace shares. One per install. wheems setup creates it.

herdr:
  version: 0.1.20

machines:
  this-mac:
    local: true

accounts:
  claude-subscription: { driver: claude }
  chatgpt-subscription: { driver: chatgpt }

connections:
  slack:
    driver: slack
    secret: slack
    allowed_users: [U012ABCDEF]

knowledge:
  embeddings:
    driver: ollama
    model: nomic-embed-text

A map of machine names to machines. Today only the local one is used.

A map of account names to accounts: what pays for models. See Engines and accounts.

A map of connection names to connections: chat apps and services, connected once and shared by every workspace. Setup creates one named slack.

See Connecting Slack.

How every workspace’s knowledge base is searched. See Knowledge base and search.

Changing the embeddings driver or model rebuilds every index the next time the service syncs it.

One per workspace, in workspaces/<id>/. The folder name is the workspace’s id. wheems init creates it.

name: Acme
description: A small design studio.
accounts: [claude-subscription]
chief_of_staff: chief-of-staff

channels:
  chat: { connection: slack, channel: acme-chat }

identity: { name: Acme chief of staff, icon: ':office:' }
skill_budget: 20

knowledge:
  note_after_idle: 30
  tidy_at: '03:00'
  filer:
    engine: claude-code
    model: claude-sonnet-5-5
    account: claude-subscription

Each channel binding is one of:

Planned · milestone 9. Validated today; nothing enforces them yet. A rule needs at least one of deny, require or approval, and approval goes with action.

rules:
  - name: release-hold
    deny: { push: [main], deploy: [production] }
  - name: review-before-merge
    require: { review: reviewer, before: merge }
  - name: deploys-need-approval
    action: deploy
    approval: approvals

YAML front matter, then the agent’s instructions in Markdown. The file name is the agent’s name.

---
description: The one entry point for Acme, aware of everything going on in it.
engine: claude-code
model: claude-opus-5-5
account: claude-subscription
permissions: auto
skills: [weekly-report]
---

# Acme: chief of staff

You are the chief of staff for Acme. Be brief. Lead with the answer.

Today the service starts only the chief of staff. Other agent files are validated and can be given skills; teams of agents arrive in milestone 5.

The skills a workspace uses, each pinned to a library version.

skills:
  weekly-report: 2

See Skills.

description: The weekly report, every Friday afternoon.
trigger: { schedule: '0 16 * * 5' }
steps:
  - agent: chief-of-staff
    task: Write the weekly report.
  - ask: { question: Send it?, channel: chat }
  - post: { channel: chat }

~/.config/wheems/secrets.json holds credentials by name, outside the install folder and out of git, readable only by your user (mode 600). Agents run as your user, so that keeps it from other users, not from agents. wheems setup writes it; you shouldn’t need to.

{
  "slack": { "bot_token": "xoxb-…", "app_token": "xapp-…" }
}

The Wheems repository has a complete example install, including the planned formats, in examples/install/. Check it with wheems validate examples/install.