getbased-agent-stack

Meta-package bundling the full getbased agent stack into one install: the MCP adapter, the local knowledge server, the browser dashboard, an orchestration CLI (init / install / connect / mcp-config), systemd user units for the knowledge server + dashboard, and paste-ready configs for Claude Code, Claude Desktop, Cursor, Cline, Codex CLI, Hermes, and OpenClaw.

Part of the getbased-agents monorepo.

Install

Requires Python 3.11 or newer. To rebuild an existing Python 3.10 tool environment while preserving configuration and library data, follow the migration instructions.

Linux, one command:

curl -sSL https://getbased.health/install.sh | bash

Runs end-to-end: installs getbased-agent-stack[full] via whichever of uv or pipx is available, exposes sibling binaries, runs a non-interactive local-only init, and starts the knowledge server + dashboard as systemd user services. Read the script first if you're cautious.

If you are connecting a private getbased profile, copy the command from Settings → Agent Access in the app. It uses the same installer and then runs getbased-stack connect for the selected client:

curl -fsSL https://getbased.health/install.sh | bash -s -- connect <target> --setup 'gbsetup_v1_...'

That setup payload contains private credentials. Keep it out of logs and public issues.

Manual — pipx:

pipx install --python python3.12 --include-deps "getbased-agent-stack[full]"

The --include-deps flag is required — it exposes getbased-mcp, lens, and getbased-dashboard alongside getbased-stack on your PATH. Without it, pipx only links the stack's own entry point and the MCP/rag/dashboard binaries stay hidden inside the venv.

Manual — uv (0.11+):

uv tool install \
  --python 3.12 \
  --with-executables-from getbased-rag \
  --with-executables-from getbased-dashboard \
  --with-executables-from getbased-mcp \
  "getbased-agent-stack[full]"

--with-executables-from is uv's equivalent of pipx's --include-deps — one tool venv, all four binaries on PATH.

Pulls:

• getbased-mcp — stdio MCP server that Claude Code / Hermes / OpenClaw spawn
• getbased-rag — local knowledge server (FastAPI + Qdrant + MiniLM/BGE)
• getbased-dashboard — web UI for library management, MCP config generation, and agent-activity inspection
• The getbased-stack discovery CLI
• [full] extra: PDF/DOCX parsers + ONNX runtime for hardware-accelerated embeddings

Total install: ~500 MB (the ML deps dominate). Smaller installs available — pipx install getbased-mcp (10 MB, agent only), pipx install "getbased-rag[full]" (RAG only), pipx install getbased-dashboard (UI + MCP; pulls rag if you want the Knowledge tab working).

Quickstart — one command

Interactive wizard:

getbased-stack init

Non-interactive (for scripted installs and curl | bash; install.sh uses this):

getbased-stack init --yes --local-only

The wizard (~30 seconds):

1. Prompts for your GETBASED_TOKEN and GETBASED_AGENT_CONTEXT_KEY when you opt into Agent Access (skip if you don't use Agent Access; --yes skips prompts)
2. Generates a rag API key if one doesn't exist
3. Writes ~/.config/getbased/env (mode 0600) — the shared config file
4. Installs systemd user units for rag + dashboard, enables them, starts them

On non-systemd hosts (Docker, macOS, WSL1) step 4 writes the unit files but skips activation with a clear message instead of crashing — re-run on a systemd-enabled host or start lens serve + getbased-dashboard serve manually.

Private setup from the app:

getbased-stack connect hermes --setup 'gbsetup_v1_...'

Manual config helper:

getbased-stack mcp-config claude-desktop   # or: claude-code, cursor, cline, codex, hermes, openclaw

The snippet carries only GETBASED_STACK_MANAGED=1 in its env block. No secrets in client configs — every MCP spawn reads the shared env file and loads the token + rag URL + API key path from there.

Open the dashboard:

http://127.0.0.1:8323

Login URL with bearer key:

getbased-dashboard login-url   # prints http://127.0.0.1:8323/?key=...

Upload docs, create libraries, manage sources, and test the MCP probe from the web UI. Rotate the sync token from the CLI (see below) or by editing ~/.config/getbased/env directly.

Surviving reboot on headless hosts

User systemd services stop on logout. On a headless server (no GUI session), they won't come back at boot unless you enable linger once:

sudo loginctl enable-linger $USER

getbased-stack init prints this reminder when it detects a headless environment. On a laptop with a GUI login, linger is nice-to-have — services start when you log in.

Other commands

getbased-stack status          # env file, unit state, linger
getbased-stack set GETBASED_TOKEN=new
getbased-stack set GETBASED_AGENT_CONTEXT_KEY=new
getbased-stack install         # re-apply unit files after package upgrade
getbased-stack uninstall       # stop + disable + remove units

Migrating from an older install

If you have a hand-rolled setup (standalone lens-rag.service, hermes-style ~/.hermes/config.yaml with MCP env), leave it alone — getbased-stack init only writes new paths and installs new unit names (getbased-rag.service, getbased-dashboard.service), so it can coexist. The opt-in loader in every binary is gated on GETBASED_STACK_MANAGED=1; without that flag set, every binary behaves exactly as before.

If you're running the existing Hermes VM deployment on this host, don't run init there. Your ~/.hermes/config.yaml continues to supply env explicitly; nothing from this package touches it.

Architecture

Claude Code / Hermes / OpenClaw          Browser
        │ MCP (stdio)                       │ HTTP
        ▼                                   ▼
  getbased-mcp                       getbased-dashboard   (localhost:8323)
   │        │                          │             │
   │ HTTP   │ HTTP                     │ proxies     │ spawns stdio for Test
   ▼        ▼                          ▼             ▼
context gateway   getbased-rag  ◀────────┘     getbased-mcp
          (localhost:8322)

The MCP holds no persistent state; it's a thin translator between MCP tool calls and two HTTP backends:

• sync.getbased.health/api/context — encrypted lab context pushed by your PWA session (authorized by Agent Access token, decrypted locally with Agent Context key)
• localhost:8322 (getbased-rag) — your local research library

The dashboard is likewise stateless — it proxies rag for Knowledge operations, imports getbased_mcp to introspect env/config, and spawns the MCP binary on demand to verify it works.

Version compatibility

Bump the meta's major when sibling protocols break; bump siblings freely for normal features.

Development

This package is the meta — the interesting code lives in sibling packages. See the monorepo root README for workspace setup.

The integration test (tests/test_integration.py) spins up lens serve in a subprocess, ingests a fixture, and exercises every MCP tool round-trip. Catches drift between the siblings the way the v1.21 catch-up drift would have been caught if the test existed then. The dashboard has its own test suite (cd packages/dashboard && uv run pytest) covering the proxy, modal logic, stdio probe, and activity-log handling.

Related docs

• packages/stack/CONTRIBUTING.md — when to bump the meta vs a sibling
• packages/stack/SECURITY.md — threat model, scope, sibling pointers

Licence

AGPL-3.0-or-later, matching the siblings.