// Set up openbrain-local-convex from a cloned repository on localhost, a LAN server, or LAN client machines. Use when the user asks to install, bootstrap, deploy, repair services, validate health, or make `brain` work end-to-end without handwaving.
| name | openbrain-setup |
| description | Set up openbrain-local-convex from a cloned repository on localhost, a LAN server, or LAN client machines. Use when the user asks to install, bootstrap, deploy, repair services, validate health, or make `brain` work end-to-end without handwaving. |
Set up this repo with fail-fast validation and no silent assumptions. Pick one mode, run exact commands, validate live behavior, and stop immediately on first broken dependency.
Primary references:
docs/SETUP.mddocs/TROUBLESHOOTING.mdscripts/deploy-server.shscripts/services.shscripts/link-global.shChoose exactly one setup path first:
localhost: user wants everything on one machine.server: user wants always-on runtime on another host.lan-client: user wants brain from another LAN machine without SSH.Run and fail fast:
node -v
npm -v
If brain is unavailable globally, either run npm run link:global once or use:
npm run brain -- <command>
If dependencies are missing, stop and report exact missing command.
Run from repo root:
npm ci
npx convex dev --configure new --dev-deployment local --once
cp .env.example .env
~/.lmstudio/bin/lms daemon up
~/.lmstudio/bin/lms runtime select llama.cpp-linux-x86_64-vulkan-avx2
~/.lmstudio/bin/lms load text-embedding-embeddinggemma-300m-qat --gpu max --yes
~/.lmstudio/bin/lms server start
npm run health
npm run brain -- stats
Optional global command:
npm run link:global
brain stats
From local machine:
bash scripts/deploy-server.sh <host> <remote_dir>
bash scripts/bootstrap-server-interactive.sh <host> <remote_dir>
ssh <host> "curl -fsSL https://lmstudio.ai/install.sh | bash"
ssh <host> "~/.lmstudio/bin/lms get embeddinggemma -n 20 -y"
ssh <host> "cd <remote_dir> && bash scripts/services.sh install"
bash scripts/services.sh install is the canonical path. It renders units, restarts services, and handles a local Convex backend upgrade when needed.
Set server .env for LAN API access:
OPENBRAIN_API_HOST=0.0.0.0
OPENBRAIN_API_PORT=8787
LMSTUDIO_BASE_URL=http://127.0.0.1:1234/v1
LMSTUDIO_EMBED_MODEL=text-embedding-embeddinggemma-300m-qat
LMSTUDIO_RUNTIME_ALIAS=llama.cpp-linux-x86_64-vulkan-avx2
LMSTUDIO_GPU_OFFLOAD=max
LMSTUDIO_REQUIRE_VULKAN=1
Then restart and verify:
ssh <host> "cd <remote_dir> && bash scripts/services.sh restart"
ssh <host> "cd <remote_dir> && npm run health"
curl -sS http://<server-ip>:8787/health
On each client machine:
npm ci
cp .env.example .env
Set .env:
OPENBRAIN_REMOTE_URL=http://<server-ip>:8787
# OPENBRAIN_API_KEY=<shared-secret-if-server-enforces-key>
Validate:
npm run brain -- stats
npm run brain -- capture "setup smoke test" --tags smoke,setup
npm run brain -- search "setup smoke test" --limit 1
Optional:
npm run link:global
brain stats
brain is not found:npm run link:global
echo "$PATH"
curl -v http://<server-ip>:8787/health
ssh <host> "cd <remote_dir> && bash scripts/services.sh status"
401):
OPENBRAIN_API_KEY matches on server and client.~/.lmstudio/bin/lms runtime ls
~/.lmstudio/bin/lms runtime survey
Do not declare success until all are true:
npm run health succeeds in target mode.brain capture succeeds.brain search returns the new capture.curl http://<server-ip>:8787/health succeeds from a client machine.