Configuration

Two files, two jobs: a machine-local store of credentials, and a committable pointer into it. Everything below is detail on those two — start with a recipe, reach for the reference tables when you need a field.

Common recipes

The setup wizard writes profiles for you; ryvem-mcp use binds a repo to one. You rarely touch the files by hand.

One account

The installer runs the setup wizard once for you. To do it by hand — or to reconfigure later — run it yourself:

ryvem-mcp setup    # interactive wizard; writes a named profile to config.json

1. Name the profile (press Enter to accept default).
2. Pick the board — Jira, Trello, or Local — and paste its credentials when asked.
3. Add the repository host your code lives on (GitHub, Bitbucket, or GitLab), then choose Done.
4. The first profile you create becomes the default automatically.

A repository with no ryvem.json already falls back to that default, so a single-account setup needs nothing more. To pin the repo explicitly — and to confirm what resolves — run:

ryvem-mcp use default    # write {"profile":"default"} into this repo's ryvem.json
ryvem-mcp use            # no argument: print what this repo resolves to

Two accounts of the same provider

A work Jira site for one project and a personal one for another — same provider, two contexts. Run the wizard twice with two names, then point each repo at the profile it needs:

ryvem-mcp setup            # name it "work",     Jira site A + its GitHub token
ryvem-mcp setup            # name it "personal", Jira site B + its token

cd ~/code/work-project
ryvem-mcp use work         # this repo now resolves the "work" profile

cd ~/code/side-project
ryvem-mcp use personal     # this repo now resolves the "personal" profile

1. Running setup again adds another named profile; it never overwrites the first. When it asks which to make default, choose the one you use most.
2. ryvem-mcp use <name> merges {"profile":"<name>"} into that repo's ryvem.json, preserving repoId and every other field.
3. Commit each ryvem.json — it names a profile, it never contains one — so teammates inherit the binding and supply their own tokens.

After ryvem-mcp update

Self-update replaces the binary only. The installer wizard does not run again, and your profiles and repo bindings are left untouched. To add or change an account afterwards, run the wizard directly:

ryvem-mcp update    # replaces the binary; profiles and bindings survive
ryvem-mcp setup     # re-run any time to add or update a profile
ryvem-mcp doctor    # read-only: confirm what is configured and what resolves

Re-running setup updates an existing profile when you give its name, or adds a new one — always through the same atomic write. When something looks off, ryvem-mcp doctor is the first stop: it prints, with no network calls, exactly which profiles exist, which one this repo resolves, and any mismatch it finds.

Reference: the two layers

Ryvem never mixes credentials with project settings. Where a secret can live and where a project binding can live are two different places, by design.

One machine can hold many profiles — a company account and a personal one, each with its own board, repositories, and knowledge base — and each repo picks the one it needs. That multi-context setup is the intended, first-class case.

Global profiles: config.json

The global store lives at ~/.ryvem/config.json. A profile is one board plus the version-control and knowledge accounts that belong to the same context. The top-level default names the profile used whenever nothing more specific is chosen.

{
  "default": "company",
  "profiles": {
    "company": {
      "board":  { "provider": "jira", "url": "https://yourco.atlassian.net", "email": "you@company.com", "token": "..." },
      "github": { "token": "..." }
    },
    "personal": {
      "board": { "provider": "local" }
    }
  }
}

You rarely edit this file by hand — the config commands read and write it for you, always through an atomic write so a crash can never leave it half-written. The setup wizard on first install writes it too.

Profile fields

Every profile has exactly one board; the account sections are optional and only added when you use that host. The board's fields depend on its provider.

The exact credential shapes, scopes, and where to create each token are covered in Providers.

The data directory

config.json lives inside Ryvem's data directory, which also holds the memory-graph database (dev.db) and a cache. It defaults to ~/.ryvem and moves wholesale when you override it.

Set RYVEM_DATA_DIR to relocate all of the above (config, database, and cache move together). On first run against the default location, an existing legacy ~/.dev-mcp directory is migrated into place automatically.

The .env alternative

Instead of — or alongside — config.json, a single profile can come from a .env file placed next to the binary (or at the package root when running from source). This is the original single-board layout, kept for full backward compatibility. Variables already set in your environment always win over the same key in .env.

ATLASSIAN_EMAIL=you@company.com
JIRA_URL=https://yourco.atlassian.net
JIRA_TOKEN=...
GITHUB_TOKEN=...

The board provider comes from RYVEM_PROVIDER (jira, trello, or local). If it is unset, Ryvem infers it from the variables that are present: any Jira variable means Jira, any Trello variable means Trello. A completely empty .env boots the zero-config local board so the server always starts.

Per-repo binding: ryvem.json

A repository declares which profile and board it works against in a ryvem.json at its root. This file holds only references — never a token — so it is safe to commit and share with your team. Credentials always come from the resolved profile; any credential-looking field written here is stripped on read.

{
  "profile": "company",
  "board": "PROJ",
  "agents": {
    "enabled": ["architect", "engineer", "security"],
    "orchestrator": "chief",
    "maxIterations": 3,
    "checks": [{ "id": "test", "run": "npm test" }, { "id": "types", "run": "npx tsc --noEmit" }],
    "gateChecks": { "architecture": ["test", "types"] }
  }
}

The file is found by walking up from the working directory to the repository's git root (or the filesystem root). A pre-rebrand dev-mcp.json is still read as a fallback, so existing repositories keep working.

How a repo resolves its profile

When a tool runs against a repository, Ryvem picks the profile — and the board — in a fixed order, taking the first value it finds:

Because the committed ryvem.json comes first, a repository's declared profile is authoritative for everyone who works in it, while a machine without that file still falls back cleanly to its own default.

Environment variables

Environment variables configure runtime paths and the .env profile. Anything set in the real environment overrides the matching line in a .env file.

Runtime and paths

.env board selection

Credential variables

The board, version-control, and knowledge credentials for the .env profile. Scopes and where to create each token live in Providers.