Providers

The provider model

Three kinds of provider sit behind small, stable contracts. Each row below is an implementation you can select; adding another is a single adapter, not a rewrite.

Credentials live in a plain .env next to the binary — written by the setup wizard or by hand. Nothing is sent anywhere; the file is read locally at start-up. This page details the two providers most often configured by hand — Jira and GitLab — and the local board that needs no credentials at all. Trello, GitHub, and Bitbucket are covered on Getting started; the full environment reference is on Configuration.

Jira

Jira is the default board provider. You need three values: your site's base URL, your Atlassian account email, and a scoped API token. The wizard asks for them in that order and writes them to .env.

Create the token

Go to Atlassian account › Security › API tokens › Create API token with scopes — the page the wizard prints, https://id.atlassian.com/manage-profile/security/api-tokens. Name it ryvem-mcp, choose the Jira product, and grant exactly these scopes:

The resulting .env keys:

RYVEM_PROVIDER=jira
JIRA_URL=https://yourco.atlassian.net
ATLASSIAN_EMAIL=you@company.com
JIRA_TOKEN=your-atlassian-api-token

Jira supports native subtasks, issue links, and comment properties, and exposes its projects as workspaces that create_task can target. It does not create boards over the API — a Jira project needs an admin and a template.

GitLab

GitLab is one of the three version-control providers (GitHub and Bitbucket are the others). Ryvem models merge requests as pull requests, addressed by their per-project iid. Set only the token for the host your repository actually uses; the origin remote decides the project on every call.

Create the token

In GitLab, go to User settings › Access tokens and create a Personal Access Token. The wizard prints the exact page for your host — https://gitlab.com/-/user_settings/personal_access_tokens for the cloud, or https://<your-host>/-/user_settings/personal_access_tokens for a self-hosted instance. One scope is required:

For gitlab.com, the token is all you need:

GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

For a self-hosted instance, add the host (no scheme, no path). Leaving it blank means gitlab.com:

GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_HOST=gitlab.yourcompany.com

Local board

The local board is what makes Ryvem run in any repository — personal or corporate, with or without a tracker. It is a full board (columns, tasks, subtasks, links, comments) backed entirely by the memory graph, so there is no external service, no account, and no network. Decline every wizard prompt and Ryvem boots on it automatically; there is nothing to create.

# No .env at all also works — this is only explicit.
RYVEM_PROVIDER=local

What it stores, and where

One board is auto-created per repository, anchored to the working copy the server runs in and keyed to that repo's graph scope (repo:<uuid>). Tasks, comments, subtasks, and links all live as graph nodes and edges — descriptions and comments are native markdown. It ships with four columns in flow order:

Task keys are <SLUG>-<n>, where the slug is derived from the repository folder name and n is a gap-free, strictly increasing counter. Everything persists in the single SQLite memory graph:

Override the parent directory with RYVEM_DATA_DIR. Because the board is just graph data, its history and search behave exactly like the rest of the memory graph.

Limits

None of this is a dead end: a card created on the local board can later be promoted to Jira or Trello once you connect one.