# installing solstone

these instructions are for a coding agent and human working together. solstone is the platform: sol is the app, and the journal is the memory it keeps. sol lives on your devices, experiences your day with you, and keeps it all in your journal — always private, only yours. open source, made by sol pbc.

**supported platforms:** linux (primary), macOS. windows is not yet supported.

the latest version of these instructions is at https://solstone.app/install.

## before you begin

### check whether solstone is already installed

```bash
sol --version 2>&1 && journal service status 2>&1
```

if `sol` isn't on PATH, the install hasn't been done yet — proceed.
if solstone is running and healthy, skip to [install sol on your devices](#install-sol-on-your-devices).

### prerequisites

linux: install `uv` (`curl -LsSf https://astral.sh/uv/install.sh | sh`) and `ripgrep` (`rg`) from your distro package manager.

macOS: install xcode command line tools (`xcode-select --install`) and homebrew (https://brew.sh), then `brew install uv ripgrep`.

## install

most people install solstone to **run the journal here** — the full host that
transcribes, makes sense of your day, and holds everything:

```bash
pip install solstone-journal                                    # includes sol on PATH
uv tool install solstone-journal && uv tool install solstone   # journal tool + sol tool
pipx install solstone-journal && pipx install solstone         # same two-tool story
```

Pick one installer.

A pip install of solstone-journal puts `sol`, `solstone`, `journal`, and
`mlx-vlm-server` on PATH (`~/.local/bin/` for uv tool and pipx, which most
shells already include). uv tool and pipx expose each installed tool's own
commands — the journal tool provides `journal` and `mlx-vlm-server`, and the
thin solstone tool provides `sol` and `solstone`, which is why their install
lines above are two commands.

NVIDIA GPU owners who want GPU-accelerated transcription install
`solstone-journal-cuda` **instead of** `solstone-journal` with the same
installer command shape.

### just the `sol` client

`pip install solstone` (no extras) installs only the thin `sol` access client —
talk to a journal running **elsewhere** (a second machine, or a journal you
reach over your private link). it carries none of the journal host's AI/media
stack, so it's small and fast:

```bash
uv tool install solstone        # the sol client, on PATH
uvx solstone --help             # or ephemerally — no install, one-shot
```

Running the journal? Check the machine first: `uvx solstone check` renders a one-shot readiness verdict (GPU, memory, free disk) for the bundled local models — no install required. It exits 0 when ready, and prints exactly what's missing when not.

A thin/no-extras install carries only `sol` and `solstone`; `journal setup`,
`journal start`, and `mlx-vlm-server` require a `solstone-journal` host install.

## set up

```bash
journal setup
```

this runs the setup readiness doctor battery, confirms the journal directory at `~/journal`, installs the local transcription model (~2.5 GB on linux), installs the `sol` skill for claude code, codex, and gemini, installs the journal-side `sol` and `journal` router skills so sol can tend the journal, and starts a background service (systemd on linux, launchd on macOS) listening on http://localhost:5015.

let your human know: **open http://localhost:5015 in a browser**. the first-run wizard walks them through setting their identity and choosing how sol thinks — local by default (the bundled model runs right in the journal), or their own provider key if the machine can't run a local model.

a `solstone-journal` install bundles everything a journal host needs — PDF rendering, whisper, and the default CPU transcription stack are all included; `journal setup` downloads the transcription model. there are no separate à-la-carte extras to add. if the readiness doctor step (`journal doctor --readiness`) finds missing system libraries, it will tell you the exact install command to run for your platform.

Pick one of `solstone-journal` or `solstone-journal-cuda` — the CPU and GPU ONNX runtimes share the same files and must not both be installed. `journal doctor` reports whether the transcription runtime and model are ready.

This CUDA extra is only for transcription. The Linux local model provider picks its own GPU backend: on NVIDIA GPUs from the RTX 30 series up with a current NVIDIA driver (580 series or newer), it runs natively on CUDA; the runtime downloads from updates.solstone.app as a checksum-pinned bundle. On other hardware GPUs (AMD, Intel, or older NVIDIA) it uses Vulkan. CPU/software Vulkan devices are rejected instead of falling back silently. On AMD, the local model path runs through Mesa/RADV Vulkan, while transcription stays on the bundled CPU runtime.

if the service fails to start, check `journal service logs`.

## choosing how to power sol

sol is powered by an AI model, and it runs **locally by default** — on every device. the bundled model runs right in your journal, so your thinking never leaves the machine. a cloud lane is an option, not the default; you choose in settings → providers (or the thinking app).

- **local is the default.** on a capable machine sol thinks locally with nothing extra to set up — the bundled model handles both the reasoning over your journal and screen analysis, and nothing is sent to a cloud provider. the practical floor is about **8 GB**: an 8 GB GPU, or 8 GB of free memory on Apple Silicon (the model is ~2.74 GB on disk, plus the ~2.5 GB transcription model). solstone checks first and won't activate a local model that won't fit; on Linux it needs a supported hardware GPU (NVIDIA via CUDA on RTX 30-series or newer, or AMD, NVIDIA, and Intel via Vulkan).
- **a cloud lane, if your machine can't clear that bar — or you'd rather not spend its power.** point solstone at Google (Gemini), OpenAI, or Anthropic with **your own developer API key**, created in that provider's developer console — *not* the consumer chat product (gemini.google.com / chatgpt.com / claude.ai). you can switch any time in settings → providers.

what actually leaves your machine differs sharply between these paths: with the local model, nothing leaves; with a hosted provider, only that task's prompt plus the relevant journal context goes, directly to that provider under your own key. solstone is never a proxy, and sol pbc is never in that path and never sees it. for the full picture of what's sent, to whom, and under whose terms, see [what solstone sends](DATA-FLOW.md).

## install sol on your devices

your journal needs sol alongside it — sol takes in your day on each device and keeps it in your journal. each platform ships its own package (the engineering docs call these observers); install one for each machine you want sol on.

**macOS:** download the signed app bundle from https://solstone.app/observers and drag it to Applications. it pairs itself with the running journal on first launch.

**linux:**

```bash
pipx install solstone-linux
solstone-linux install-service
journal observer create laptop      # mint a key for this observer
```

`solstone-linux install-service` walks you through pointing the observer at the key you just minted. swap `laptop` for any name you'd like to identify this machine by.

**tmux terminal sessions:**

```bash
pipx install solstone-tmux
solstone-tmux install-service
journal observer create tmux-laptop
```

(for observer packages, `uv tool install solstone-tmux` is also fine if you prefer uv.)

## migrating from a pre-split install

If you installed the journal before the package split, run the one-time migration
line for your installer family, then run `journal setup`.

```bash
pip uninstall solstone-journal-host && pip install solstone-journal
pipx uninstall solstone && pipx install solstone-journal && pipx install solstone
uv tool uninstall solstone && uv tool install solstone-journal && uv tool install solstone
```

## upgrading

```bash
pip install --upgrade solstone-journal && journal setup
uv tool install --upgrade solstone-journal && uv tool install --upgrade solstone && journal setup
pipx upgrade solstone-journal && journal setup
```

Use the same installer family you used for install. The `uv tool` form upgrades both
the journal package and the thin `solstone` client, while the pipx form upgrades
the journal tool. For GPU transcription, upgrade `solstone-journal-cuda` instead
of `solstone-journal`. The `journal setup` step refreshes runtime artifacts and
reconciles the systemd/launchd unit if anything has changed.

## upgrading an existing journal

The steps above cover the package upgrade. If you already have a journal with history in it, three more things happen (or need to happen) on top of that:

**one-time maintenance tasks.** Some upgrades ship a one-time migration that runs automatically the next time the service starts — you don't need to do anything. `journal maint --list` shows what ran and what's pending; `journal maint <task>` shows details and log output for one.

**search index rebuild, if you're coming from before 0.7.0.** A pre-0.7.0 search index is dropped and rebuilt on first open after upgrade. The rebuild usually queues itself automatically, but if the service was still starting up when that happened, it can miss the window and print a message asking you to run it yourself. If search feels empty (or noticeably thinner than your journal's actual history) right after upgrading from a pre-0.7.0 install, run:

```bash
journal indexer --rescan-full
```

This is a full historical rescan — it can take a while on a large journal.

**connections/edges backfill, if you're coming from before 0.8.3.** The relationship layer between entities (who's connected to whom, and how) is derived by a separate pass. `journal indexer --rescan` (and the automatic light rescan on service start) only covers today plus facets/imports/apps — it does **not** backfill edges over your existing history. To build connections for days you already have:

```bash
journal indexer --rebuild-edges
```

Run this once after upgrading to a version with the connections feature if your existing days show no connections.

**if your journal isn't at the default location.** `journal setup` expects `~/journal` unless told otherwise. If your journal lives somewhere else — including if you're on an early source install that relied on the now-retired source-tree fallback (running `journal setup` from inside a git checkout used to default the journal into `<repo>/journal`) — point setup at it explicitly so it reuses that journal instead of creating an empty one at the default path:

```bash
journal setup --journal /path/to/your/journal --accept-existing-journal
```

Skipping `--journal` here silently resolves to `~/journal` and starts fresh — a real risk on the source-tree-fallback case, since a fresh `~/journal` looks like a working install even though your actual history is untouched at the old path.

## uninstall

1. remove setup-managed runtime files: `journal setup --clean-uninstall`
   this removes the user service, managed `~/.local/bin/sol` wrapper, user config, and setup manifest. it does not remove your journal.
2. optional: remove the installed `sol` agent skill: `sol skills uninstall`.
3. uninstall the python packages: `uv tool uninstall solstone-journal && uv tool uninstall solstone` (or `pipx uninstall solstone-journal`).
4. macOS only: drag `/Applications/solstone.app` to Trash.
5. macOS only, optional: remove observer app data and the parakeet model cache:
   ```bash
   rm -rf ~/Library/Application\ Support/solstone/
   ```
   this evicts the ~2.5 GB parakeet cache; reinstall will re-download it.
6. macOS only, optional: reset privacy permissions:
   ```bash
   tccutil reset Microphone app.solstone.observer && tccutil reset ScreenCapture app.solstone.observer
   ```
   or use System Settings → Privacy & Security.

## done

once it's running, sol experiences your day along with you and keeps it all in your journal — conversations transcribed, people and projects surfaced, a knowledge graph built, everything searchable at http://localhost:5015. your journal is one folder per day, always private, only yours.

source code: https://github.com/solpbc/solstone-journal
company: https://solpbc.org

## feedback

questions, feedback, or a bug? **follow and tag [@solstone.app](https://bsky.app/profile/solstone.app) on Bluesky** for discussion and updates, open an issue at https://github.com/solpbc/solstone-journal/issues for bugs, or reach support at https://support.solstone.app. you don't need to know anyone — those are the front doors.

(running into trouble or want to develop on solstone yourself? see [CONTRIBUTING.md](CONTRIBUTING.md).)
