> ## Documentation Index
> Fetch the complete documentation index at: https://meridiona-mintlify-2ae70a19.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Meridian: All Environment Variables Explained

> Learn where Meridian's config files live, how to edit them, and what every environment variable does — from polling intervals to PM credentials.

Meridian is configured entirely through environment variables. There are no config files with special formats or UI settings to hunt down — every option is a key-value pair in a single `.env` file. `meridian setup` creates the file and you can edit it at any time.

## Where configuration lives

The npm install lays out the runtime under `~/.meridian/`:

| Path                                           | Purpose                                                                     |
| ---------------------------------------------- | --------------------------------------------------------------------------- |
| `~/.meridian/app/.env`                         | The one backend config — read by the daemon, classifier, and worklog stage. |
| `~/.meridian/meridian.db`                      | The session database.                                                       |
| `~/.meridian/logs/`                            | Per-service logs (daemon, MLX server, screenpipe, UI).                      |
| `~/Library/LaunchAgents/com.meridiona.*.plist` | The launchd agents registered by `meridian setup`.                          |

Contributors building from source share the same on-disk layout, except their config lives at the **repo-root `.env`** instead of `~/.meridian/app/.env` (the source checkout is what `meridian dev` runs against).

## Editing configuration

To open the config in your `$EDITOR`, run:

```bash theme={null}
meridian config edit
```

This opens `~/.meridian/app/.env` (or the repo-root `.env` for source builds). After saving, restart for the change to take effect:

```bash theme={null}
meridian restart
```

## Environment variable reference

### Core daemon settings

These variables control how the Rust daemon reads screenpipe data and classifies sessions. All of them are optional — the defaults work out of the box.

| Variable                   | Default                   | Description                                                                                               |
| -------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------- |
| `SCREENPIPE_DB`            | `~/.screenpipe/db.sqlite` | Path to screenpipe's SQLite database. Meridian opens this read-only.                                      |
| `MERIDIAN_DB`              | `~/.meridian/meridian.db` | Path where Meridian writes its own session database. Created on first run.                                |
| `POLL_INTERVAL_SECS`       | `60`                      | How often (in seconds) the daemon checks screenpipe for new frames.                                       |
| `CLASSIFICATION_ENABLED`   | `true`                    | Set to `false` to run activity tracking and categorisation only, with no MLX server needed.               |
| `MLX_SERVER_PORT`          | `7823`                    | The port the persistent MLX inference server listens on.                                                  |
| `CLASSIFICATION_TIMEOUT_S` | `120`                     | Per-session inference timeout in seconds. Increase this if you see timeout errors on long sessions.       |
| `CLASSIFIER_BACKEND`       | `mlx`                     | Classification backend. Set to `mlx` when using the MLX inference server (recommended for Apple Silicon). |

<Note>
  Setting `CLASSIFICATION_ENABLED=false` lets you run Meridian in activity-tracking mode. The daemon still reads screenpipe frames, builds app sessions, and assigns activity categories — it just skips the ticket-linking step and doesn't require the MLX server to be running. This is useful if you're not ready to configure PM credentials or just want to explore the session data first.
</Note>

### Jira

All three credential variables are required to enable the Jira connector. `JIRA_PROJECT_KEYS` is optional — omitting it syncs across all projects your account can access.

| Variable            | Default          | Description                                                                                                                                                 |
| ------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JIRA_BASE_URL`     | *(none)*         | Your Atlassian instance URL, e.g. `https://your-org.atlassian.net`.                                                                                         |
| `JIRA_EMAIL`        | *(none)*         | The email address associated with your Atlassian account.                                                                                                   |
| `JIRA_API_TOKEN`    | *(none)*         | An Atlassian API token. Generate one at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens). |
| `JIRA_PROJECT_KEYS` | *(all projects)* | Comma-separated project keys to scope ticket lookups, e.g. `KAN,ENG`. Leave empty to search all accessible projects.                                        |

### GitHub

Both credential variables are required to enable the GitHub connector. `GITHUB_REPOS` is optional — omitting it covers all repositories in your org.

| Variable       | Default           | Description                                                                                                                             |
| -------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `GITHUB_TOKEN` | *(none)*          | A GitHub personal access token with `repo` scope.                                                                                       |
| `GITHUB_ORG`   | *(none)*          | Your GitHub organisation name.                                                                                                          |
| `GITHUB_REPOS` | *(all org repos)* | Comma-separated list of `org/repo` slugs to scope issue lookups, e.g. `your-org/api,your-org/web`. Leave empty to search all org repos. |

### Linear

The API key is required to enable the Linear connector. `LINEAR_TEAM_IDS` is optional.

| Variable          | Default       | Description                                                                                                                       |
| ----------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `LINEAR_API_KEY`  | *(none)*      | A Linear API key. Generate one in your Linear workspace under **Settings → API**.                                                 |
| `LINEAR_TEAM_IDS` | *(all teams)* | Comma-separated team identifiers to scope issue lookups, e.g. `TEAM1,TEAM2`. Leave empty to search all teams your key can access. |

## Minimal working configuration

The smallest configuration that enables activity tracking, session categorisation, and Jira ticket sync is:

```bash title="~/.meridian/app/.env" theme={null}
# Required for task classification and Jira sync
JIRA_BASE_URL=https://your-org.atlassian.net
JIRA_EMAIL=you@your-org.com
JIRA_API_TOKEN=your-api-token

# Enable classification (default: true — shown here for clarity)
CLASSIFICATION_ENABLED=true
```

Everything else defaults to safe values and can be added incrementally.

## Editing credentials later

The npm install does not include an interactive credential prompt — edit the file directly:

```bash theme={null}
meridian config edit
meridian restart
```

Contributors who built from source can re-run `./install.sh --skip-permissions` to be re-prompted for any variable that isn't already set; `./install.sh --skip-env` bypasses the prompt flow entirely.

<Tip>
  You can edit the `.env` with any text editor and then run `meridian restart`. The daemon reads the file once at startup and does not hot-reload changes.
</Tip>