Installation

Windows #

On Windows you install Grounded Companion, a small app that lives in the system tray. Companion installs Grounded Core for you and keeps both itself and Core up to date.

Where things live once Core is installed:

• Your memory is in %USERPROFILE%\Grounded, the Grounded folder in your user folder beside Documents and Downloads. It is deliberately not inside Documents, which OneDrive often syncs: a live database in a synced folder can be corrupted.
• Core runs as a scheduled task named Grounded, just for your user. No admin rights, no Docker, no window. It starts when you sign in, keeps running in the background and on battery, and restarts itself if it crashes.
• The console opens at http://127.0.0.1:7437. Companion has a button for it.

macOS & Linux #

Run the install script, then grounded install. The script puts the grounded command on your machine; grounded install starts the service.

What you need first: Node.js 26, the version this release was built with. Grounded runs on your system Node and the script checks it: if the version doesn't match, it stops and tells you which one to install. It never installs Node for you. You also need Docker or systemd to run the service.

What the script does, in order:

• Reads the release manifest from GitHub Releases and picks the build for your system.
• Downloads it and checks its size and SHA-256 against both the manifest and the release's SHA256SUMS. Any mismatch and it refuses to install.
• Unpacks it to ~/.grounded/lib/<version> and points ~/.grounded/lib/current at it.
• Puts a grounded launcher in ~/.local/bin, and tells you if that folder isn't on your PATH.
• Starts nothing. That's grounded install's job.

Pass options after sh -s --: --version 0.2.0 installs a specific release instead of the latest, and --prefix DIR puts the launcher somewhere other than ~/.local/bin.

Check it works #

Open http://127.0.0.1:7437 in a browser. If the console loads, Core is running. On macOS and Linux you can also ask from the terminal:

GET /health reports the installed version, which is how Companion knows when an update is available. Next: the quickstart.

Updating #

• Windows — Companion checks for new Core releases and shows a badge when one is out. Update from its Settings page. Companion updates itself the same way.
• macOS & Linux — run the install script again, then grounded restart. The new release unpacks beside the old one and current switches over; the previous version stays in ~/.grounded/lib, so --version rolls back.

Your data is never touched by an update. Core migrates its database on startup, and that is safe to run any number of times.

Advanced: backends #

grounded install checks what your machine can run and only offers those options. With no flags it asks; on a non-interactive shell it picks a sensible default.

Install also refuses to stack a second copy on top of a running one (unless you pass --force), creates the cabinet with a default config.toml, waits until /health answers, and records how it deployed so start, stop and status know what to manage. The config holds no absolute paths, so a cabinet can move between Docker and systemd without edits.

Two folders, on every system. Your data — grounded.db, docs, exports, backups — lives in ~/Grounded/Cabinet (%USERPROFILE%\Grounded\Cabinet on Windows). ~/.grounded holds only configuration, models and runtime: config.toml, install.json, logs, lib/ and add-ons. A custom --home folder keeps its data inside it, in cabinet/.

Upgrading an older install whose data is still in ~/.grounded/cabinet? It keeps working there; Grounded never switches to a new, empty cabinet. grounded status says so, and grounded migrate-cabinet stops the service, moves the data to ~/Grounded/Cabinet, checks it and starts the service again. It refuses if the new folder already holds files.

Recall works on keywords out of the box, with no model running. For search by meaning, turn on the Embeddings add-on or point the config at Ollama. For Postgres, TLS and the full config, see self-hosting.

Flags #

Uninstall #

grounded uninstall removes the service and keeps your data. grounded uninstall --purge also deletes ~/Grounded and ~/.grounded, and with them every fact, session and doc. It asks first.