getbased-agents

Monorepo for the getbased agent ecosystem — MCP server, RAG backend, web dashboard, and a meta-package that wires them together.

Package	PyPI	Role	Contents
getbased-mcp	getbased-mcp	MCP adapter for Claude Code / Hermes / OpenClaw / any MCP client	stdio ↔ HTTP
getbased-rag	getbased-rag	Local RAG knowledge server. Also the PWA's "External server" Knowledge Base backend	FastAPI + Qdrant + MiniLM/BGE
getbased-dashboard	getbased-dashboard	Browser UI: manage knowledge libraries, generate MCP client configs, see agent activity	FastAPI + vanilla JS
getbased-agent-stack	getbased-agent-stack	Meta-package pinning all three siblings	thin CLI + systemd unit + example configs

Claude Code / Hermes / OpenClaw           Browser
        │ MCP (stdio)                       │ HTTP
        ▼                                   ▼
  getbased-mcp                    getbased-dashboard  (localhost:8323)
   │        │                        │             │
   │ HTTP   │ HTTP                   │ proxies     │ spawns stdio
   ▼        ▼                        ▼             ▼
sync GW   getbased-rag  ◄──────────┘         getbased-mcp
          (localhost:8322)

Install

Linux, zero-friction — curl | bash:

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

The script auto-detects uv or pipx (install either one first if you have neither), installs getbased-agent-stack[full] with sibling binaries exposed, runs getbased-stack init --yes, and starts getbased-rag + getbased-dashboard as systemd user services. Read it first if you're cautious — curl -sSL https://getbased.health/install.sh.sha256 | sha256sum -c verifies the published hash.

Manual install (macOS, Windows, WSL1, or if you'd rather not run a shell script):

# pipx — --include-deps exposes lens, getbased-dashboard, getbased-mcp on PATH
pipx install --include-deps "getbased-agent-stack[full]"

# or uv (0.11+)
uv tool install \
  --with-executables-from getbased-rag \
  --with-executables-from getbased-dashboard \
  --with-executables-from getbased-mcp \
  "getbased-agent-stack[full]"

Or pick the piece you actually need:

pipx install getbased-mcp            # agents for lab data only, no RAG  (~10 MB)
pipx install "getbased-rag[full]"    # RAG backend for the PWA, no agents (~500 MB)
pipx install getbased-dashboard      # web UI; pulls the MCP dep alongside it

Quickstart (manual)

pipx install --include-deps "getbased-agent-stack[full]"
getbased-stack init --yes                  # non-interactive: token skipped, API key
                                           # auto-generated, systemd units installed
                                           # and started. Drop --yes for the wizard.
getbased-stack mcp-config claude-desktop   # paste the snippet into your MCP client

--include-deps exposes getbased-mcp, lens, and getbased-dashboard alongside getbased-stack on your PATH — without it, pipx hides the sibling binaries inside the venv. See packages/stack/README.md for the full flow including linger-for-headless and token rotation.

Development

git clone https://github.com/elkimek/getbased-agents
cd getbased-agents
uv sync --all-packages --all-extras

Each package runs its own tests from its own directory:

(cd packages/mcp && uv run pytest)       # 33 unit tests, respx-mocked HTTP
(cd packages/rag && uv run pytest)       # 51 tests, FastAPI TestClient + fake embedder
(cd packages/dashboard && uv run pytest) # 64 tests, respx-mocked rag + real-subprocess MCP probe
(cd packages/stack && uv run pytest)     # 2 integration tests: real lens subprocess + real MCP tool calls

CI runs the same matrix on Python 3.10/3.11/3.12 (unit) + 3.12 (integration) on every push and PR.

Per-package details:

• packages/mcp/README.md + CONTRIBUTING + SECURITY
• packages/rag/README.md + CONTRIBUTING + SECURITY
• packages/dashboard/README.md
• packages/stack/README.md + CONTRIBUTING + SECURITY

Releases

All four packages publish to PyPI automatically on tag push. Bump a version, commit, tag with vX.Y.Z or <pkg>-vX.Y.Z, and push the tag — the publish workflow builds every package, uploads the bumped ones, and skip-existings the rest.

Full step-by-step in RELEASING.md. Meta-package bump policy is in packages/stack/CONTRIBUTING.md.

Repo history

This repo was formed by merging three previously-separate repos. History is preserved via git subtree add:

• elkimek/getbased-mcp → packages/mcp/ (archived)
• elkimek/getbased-rag → packages/rag/ (archived)
• elkimek/getbased-agent-stack → packages/stack/ + root scaffolding (renamed to this repo)

packages/dashboard/ is new in this repo, not inherited from an archive.

PyPI package names stay the same — the merge is repo-layout only.

Licence

GPL-3.0-only, consistent across all four packages.