>_grounded install

Run it on your own ground.

Grounded is a small service and a folder you own — a single SQLite file by default, no database to stand up. No managed cloud, no vendor on the path. On Windows, Grounded Companion installs it for you; on macOS and Linux, one script and one command run it under Docker or systemd. Either way, your agents wake to cited recall.

[ 01 ] Prerequisites what you need [ 02 ] Deploy three paths [ 03 ] Configure one file [ 04 ] Operate backup · upgrade
Stage 01 — what you need

Modest by design.

grounded install preflight
$grounded install
✓ docker — daemon reachable
✓ systemd — user + system available
✓ embeddings — ollama · nomic-embed-text
✓ cabinet ~/Grounded/Cabinet — writable
→ service up http://127.0.0.1:7437
Node.js 26 macOS and Linux: the release runs on your system Node, which must match the version it was built with. On Windows, Grounded Companion handles the install instead. required
Docker or systemd One backend to run the service (on Windows, a scheduled task). The installer detects what your host supports. required
Embedder Ollama (offline) or an API for hybrid recall. Skip it and Grounded runs lexical-only. optional
Resources 1 vCPU, 512 MB RAM, ~50 MB disk to start. Grows with the cabinet, not with traffic. minimum
0
GPUs
0
Vendor lock-in
0
Extra DBs
0
Command to install
Stage 02 — choose a path

Three ways to stand it up.

Same substrate, different operational shape. Start local in minutes, or go reproducible the moment more than one person needs it.

zsh — macOS / Linux
# nothing to set up first — SQLite is built in
$curl -fsSL https://getgrounded.dev/install.sh | sh
$grounded install
✓ backend   systemd-user
✓ cabinet ~/Grounded/Cabinet · sqlite-vec + FTS5
$grounded status
→ running 127.0.0.1:7437 · 0 vendors
Best for

A single operator who wants continuity on their own machine in a few minutes. Everything stays local; the embedding model can run offline.

→ fastest to first recall
compose.yaml
services:
  grounded:
    image: grounded:latest
    ports: [ "7437:7437" ]
    volumes: [ ./grounded:/cabinet ]
    restart: unless-stopped
# SQLite lives in the cabinet — no db service
$grounded install --method docker
✓ container healthy · cited recall live
Best for

Anyone who wants the service pinned and reproducible. The cabinet lives in ./grounded beside the compose file — commit it, back it up, move it.

→ same on every machine
/etc/systemd/system/grounded.service
[Service]
ExecStart=grounded-api
Environment=GROUNDED_API_HOST=0.0.0.0
Environment=GROUNDED_API_PORT=7437
Restart=always
[Install]
WantedBy=multi-user.target
$grounded install --method systemd-system
✓ wrote the unit · active (running)
# front with Caddy / nginx for TLS + auth
Best for

A team that wants one always-on cabinet on shared infra. Run it as a service, bind it to your network, and put your own reverse proxy with TLS and auth in front.

→ persistent, shared, yours
Stage 03 — one file

All the knobs, in one place.

~/.grounded/config.tomltoml
[storage]
adapter="sqlite"①
path = "~/Grounded/Cabinet/grounded.db"
# adapter = "postgres"; url = "postgres://…"
[embeddings]
provider="ollama"# openai · none②
model = "nomic-embed-text"
dims = 768
[recall]
rrfK=60③
①
storage.adaptersqlite is one portable file. Switch to postgres and set url for scale.
②
embeddings.providerollama keeps every byte offline. none drops to lexical-only — no model at all.
③
recallRRF k, pinned / importance / recency / active-doc boosts, and per-source caps — every knob in the open.
env vars override every key — e.g. GROUNDED_DB_URL, GROUNDED_API_PORT.
Stage 04 — keep it running

It's files. Operate it like one.

>_ Backup
$tar czf grounded-$(date +%F).tgz ~/Grounded/Cabinet ~/.grounded/config.toml
# postgres adapter? pg_dump your grounded schema
Your data is one folder, the config one file — a SQLite db and a config.toml. Cron it like any other backup.
>_ Restore
$tar xzf grounded-2026-07-12.tgz -C ~/
$grounded restart
Drop the folder back, restart the service, and pick up exactly where you left off.
>_ Upgrade
$curl -fsSL https://getgrounded.dev/install.sh | sh
$grounded restart
✓ new release beside the old · schema migrates on start
Re-running the script installs the latest release next to the old one and switches over. On Windows, Companion keeps Core up to date for you. The service self-migrates on startup, so your records never change shape under you.
>_ Health
$grounded status
● running · docker · postgres + ollama · indexed
One command — or GET /health — tells you the service is up, indexed, and answering.
Stays on your infra
Nothing leaves the box except the embedding call — and a local model keeps even that offline.
You hold the keys
Bind to localhost for solo work; for teams, front it with your own auth and TLS.
Audit anything
Files plus Postgres you control — inspect, diff, rotate, and back up like the rest of your stack.
Your ground, your rules

Stand it up in an afternoon.

>_ curl -fsSL https://getgrounded.dev/install.sh | sh

macOS and Linux. On Windows, download Grounded Companion and it installs Core for you.

Pick a deployment How it works