Quickstart: From Zero to a Running Meridian Install

Install Meridian from npm, grant screenpipe permissions, connect your issue tracker, and get automatic worklog drafts flowing — step by step, from zero to running.

This guide walks you through getting Meridian running on your machine for the first time. Meridian is distributed as an npm package that ships a prebuilt binary — there is nothing to clone and nothing to compile. By the end you’ll have all background services running, your issue tracker connected, and your first activity sessions appearing in the dashboard. The whole process takes about 10 minutes, mostly spent waiting for the on-device model to download on first run.

Platform: macOS on Apple Silicon (M1 or later). The on-device model requires Metal; Intel Macs are not supported. You also need Node.js (any modern version) for npm — brew install node if you don’t already have it.

1. Install Meridian

   The recommended path is the bootstrap one-liner. It handles the most common stock-macOS gotcha (a root-owned npm prefix that makes npm install -g fail with EACCES) before installing Meridian and running setup:

   curl -fsSL https://raw.githubusercontent.com/Meridiona/meridian/main/scripts/bootstrap.sh | bash
   

   The script verifies you’re on Apple Silicon, confirms Homebrew and Node are present, redirects the npm global prefix to ~/.npm-global (user-owned) if it’s currently root-owned, patches your shell profile so the change persists, installs @meridiona/meridian from npm, and then hands off to meridian setup. Re-running is safe — every step is idempotent, and sudo is never required.

   Prefer to inspect the script first? Download it, read it, then run it locally:

   curl -fsSL -o bootstrap.sh \
     https://raw.githubusercontent.com/Meridiona/meridian/main/scripts/bootstrap.sh
   less bootstrap.sh
   bash bootstrap.sh
   

   If your npm global prefix is already user-writable (typical with Homebrew Node at /opt/homebrew), you can skip the bootstrap and install directly:

   npm install -g @meridiona/meridian
   meridian setup
   

   Either way, meridian setup copies the prebuilt app bundle into ~/.meridian/app, installs any missing prerequisites (Homebrew packages, Python 3.11, ffmpeg, screenpipe), prepares the on-device model environment, and registers four launchd agents that start automatically:

   Service	Role
   screenpipe	Captures your screen activity (the data source; audio capture is disabled)
   Meridian daemon	The pipeline — ETL, classification, coding-agent ingest, worklog drafting
   MLX server	The on-device model used for classification and worklog synthesis
   Dashboard	The web UI at http://localhost:3939

   Piped install (curl | bash) has no TTY for interactive prompts, so the bootstrap runs meridian setup --skip-permissions and reminds you to open a new terminal and run meridian setup to grant macOS permissions and collect tracker credentials. Running the script directly with bash bootstrap.sh hands off to the full interactive setup in the same terminal.

   Pin a specific version with npm install -g @meridiona/meridian@<version>. To update later, run meridian update.

   Gatekeeper bypass (unsigned v1 builds). The current release ships an unsigned binary. If macOS blocks it on first run, clear the quarantine attribute and restart:

   xattr -dr com.apple.quarantine ~/.meridian/app
   meridian restart
   
2. Grant screenpipe the required macOS permissions

   screenpipe needs two macOS privacy permissions that only you can grant. meridian setup opens each pane interactively; if you skipped that step or need to re-grant later, run:

   meridian permissions
   

   The two permissions screenpipe requires are:

   • Screen Recording — to capture frames and OCR text
   • Accessibility — to read window titles and accessibility tree events

   For each pane, click the + button in System Settings, navigate to the screenpipe binary, and toggle it on. Audio capture is disabled by default, so no Microphone permission is required.

   After granting access, run meridian restart so screenpipe picks up the permissions.

3. Connect your issue tracker

   Meridian drafts worklogs against tickets assigned to you. It supports Jira, Linear, and GitHub — pick whichever you use (you can configure more than one). Open the config in your $EDITOR:

   meridian config edit
   

   This opens ~/.meridian/app/.env. Add the block for your tracker. For Jira, that’s:

   JIRA_BASE_URL=https://your-org.atlassian.net
   JIRA_EMAIL=[e-mail]
   JIRA_API_TOKEN=your-api-token
   # JIRA_PROJECT_KEYS=KAN,ENG   # optional filter; empty = all projects
   
   CLASSIFICATION_ENABLED=true
   

   Save, then restart:

   meridian restart
   

   See the Jira and GitHub & Linear guides for the equivalent setup for each tracker, and the Configuration page for the full variable reference.

4. Verify everything is running

   Confirm all four services are up:

   meridian status
   

   You should see com.meridiona.screenpipe, com.meridiona.daemon, com.meridiona.mlx-server, and com.meridiona.ui reported as running with their process IDs. If anything is off, run meridian doctor for a full health check.

   First-run model download. On the first meridian start after install, the MLX server downloads the on-device model (~6 GB) into your local cache. Subsequent starts load from cache in around 5 seconds. Tail the progress with meridian logs mlx-server -f — you’ll see MLX model ready once it’s loaded.

5. Open the dashboard

   With the services running, open your browser to:

   http://localhost:3939
   

   The dashboard shows a real-time timeline of your app sessions coloured by activity category, a daily breakdown chart, and your draft worklogs. New sessions appear every 60 seconds as the daemon processes the latest screenpipe frames.

   Change the port by setting MERIDIAN_UI_PORT in ~/.meridian/app/.env, then meridian restart.

Useful commands after starting

Once Meridian is running, these are the commands you’ll reach for most often:

# Watch the daemon pipeline live
meridian logs -f

# Tail a specific service log
meridian logs daemon-error
meridian logs mlx-server
meridian logs screenpipe
meridian logs ui

# Today's worklog drafts (done / pending / per-ticket comments)
meridian worklog-status

# Diagnose missing config, services, or permissions
meridian doctor

# Stop / restart everything
meridian stop
meridian restart

# Update to the latest release
meridian update

meridian doctor checks that all launchd plists are installed, screenpipe is running and has a database, the MLX server is reachable, and the dashboard has been built. Run it any time something looks wrong.

Nothing posts to your tracker automatically. The daemon only drafts worklogs; you review and approve each one in the dashboard’s Worklogs view, and the daemon posts approved worklogs within ~60s. Approval is the only gate.

Troubleshooting

`npm install -g` fails with EACCES

Your npm global prefix is root-owned — typical with the stock macOS Node install at /usr/local. The bootstrap one-liner at the top of this page fixes this automatically by redirecting the prefix to ~/.npm-global and patching your shell profile. Run it instead of npm install -g directly:

curl -fsSL https://raw.githubusercontent.com/Meridiona/meridian/main/scripts/bootstrap.sh | bash

Never run npm with sudo — that creates root-owned files in your home and breaks future installs.

meridian status shows a service as 'not running'

Run meridian doctor to identify the specific failure. The most common causes are a missing config file (re-run meridian setup), screenpipe permissions not yet granted (meridian permissions), or a Gatekeeper block on the unsigned binary — see the warning at the top of step 1.

macOS blocks the binary on first launch

Unsigned v1 builds are quarantined by Gatekeeper. Clear the attribute and restart:

xattr -dr com.apple.quarantine ~/.meridian/app
meridian restart

The dashboard at localhost:3939 isn't loading

Give it ~15 seconds after meridian start for the Next.js server to boot, then check meridian logs ui-error -n 50. If the port is in use, set MERIDIAN_UI_PORT in ~/.meridian/app/.env and meridian restart.

Sessions appear but no worklogs are being drafted

Confirm your tracker credentials with meridian config edit, that CLASSIFICATION_ENABLED=true, and that the MLX server is up (meridian logs mlx-server -f should show MLX model ready). Inspect the day’s drafts with meridian worklog-status.

Build from source (contributors only)

If you’re contributing to Meridian itself rather than just using it, clone the repository and run the source installer instead of the bootstrap one-liner. This builds the daemon and dashboard from source and registers the same launchd services:

git clone https://github.com/Meridiona/meridian
cd meridian
./install.sh

The source path is intended for development — use meridian dev to rebuild and restart after edits. Everyone else should stick with the bootstrap install above.