getbased-agent-stack 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

getbased_agent_stack/__init__.py

@@ -5,4 +5,4 @@ plus a small CLI that proxies to the real binaries. Everything
 interesting lives in the sibling repos.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.4.0"

getbased_agent_stack/cli.py

@@ -1,72 +1,366 @@
-"""Thin CLI wrapper that proxies to getbased-rag's `lens` and getbased-mcp's
-runner. Kept minimal so users can still call `lens` / `getbased-mcp`
-directly — this exists only for discoverability ("what commands do I have
-after `pipx install getbased-agent-stack`?")."""
+"""getbased-stack — orchestration CLI.
+
+Subcommands:
+  init           — interactive one-time setup: token, API key, systemd units
+  install        — install/refresh the bundled systemd user units
+  uninstall      — stop, disable, and remove the systemd units
+  status         — show env file, units, and linger state
+  set KEY=VALUE  — upsert a single var in the shared env file
+  mcp-config CLIENT — print the MCP client config snippet
+  version        — print installed package versions
+  info / serve / everything else → delegate to the `lens` CLI
+
+Deliberate zero-dep: argparse + stdlib only. No typer, no click, no
+python-dotenv. The env file format is simple enough that we own it.
+"""
 from __future__ import annotations
 
+import argparse
+import os
+import secrets
+import shutil
 import sys
+from pathlib import Path
 
+from . import env_file, mcp_configs, units
 
-HELP = """\
-getbased-stack — thin wrapper over the two binaries installed by this package.
 
-Real commands (use directly, they're also on your PATH):
-  lens                      — getbased-rag CLI (serve, ingest, stats, ...)
-  getbased-mcp              — getbased-mcp stdio server (spawned by agents)
+# ── helpers ───────────────────────────────────────────────────────────
 
-This wrapper only exists for discoverability:
-  getbased-stack serve      → lens serve
-  getbased-stack info       → lens info
-  getbased-stack version    → print the installed package versions
 
-Quick start:
-  1. `getbased-stack serve &`           start the RAG server
-  2. `lens ingest /path/to/papers`      index your docs
-  3. configure your MCP agent (Claude Code, Hermes) — see the README
-"""
+def _default_api_key_file() -> Path:
+    xdg = os.environ.get("XDG_DATA_HOME") or os.path.expanduser("~/.local/share")
+    return Path(xdg) / "getbased" / "lens" / "api_key"
 
 
-def main() -> int:
-    import getbased_agent_stack
+def _ensure_api_key(path: Path) -> str:
+    """Generate a key if missing; return the key text either way. Mode 0600."""
+    if path.exists():
+        return path.read_text(encoding="utf-8").strip()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    key = secrets.token_urlsafe(32)
+    path.write_text(key + "\n", encoding="utf-8")
+    os.chmod(path, 0o600)
+    return key
 
-    argv = sys.argv[1:]
-    if not argv or argv[0] in ("-h", "--help", "help"):
-        print(HELP)
-        return 0
 
-    cmd, rest = argv[0], argv[1:]
-    if cmd == "version":
-        try:
-            import getbased_mcp  # noqa: F401
-            import lens  # noqa: F401
-            import importlib.metadata as md
-            print(f"getbased-agent-stack {getbased_agent_stack.__version__}")
-            try:
-                print(f"  getbased-mcp {md.version('getbased-mcp')}")
-            except md.PackageNotFoundError:
-                print("  getbased-mcp (not installed)")
+def _prompt(msg: str, default: str = "", secret: bool = False) -> str:
+    """Non-intrusive readline prompt. Treats EOF/Ctrl-D as 'use default'."""
+    suffix = f" [{default}]" if default else ""
+    try:
+        if secret:
+            import getpass
+
+            answer = getpass.getpass(f"{msg}{suffix}: ")
+        else:
+            answer = input(f"{msg}{suffix}: ")
+    except EOFError:
+        return default
+    return answer.strip() or default
+
+
+def _display_value(key: str, value: str) -> str:
+    """Mask only actual secrets (a variable NAMED token/key/secret/password).
+    Keys like LENS_API_KEY_FILE that hold a path, not a secret, show verbatim."""
+    upper = key.upper()
+    # Values that end with _FILE or _PATH are filesystem paths — show them.
+    if upper.endswith(("_FILE", "_PATH", "_DIR", "_HOME", "_URL")):
+        return value
+    if any(upper.endswith("_" + s) or upper == s for s in ("TOKEN", "KEY", "SECRET", "PASSWORD")):
+        return "****" + value[-4:] if len(value) > 4 else "****"
+    return value
+
+
+def _yesno(msg: str, default: bool = True) -> bool:
+    suffix = "[Y/n]" if default else "[y/N]"
+    try:
+        ans = input(f"{msg} {suffix}: ").strip().lower()
+    except EOFError:
+        return default
+    if not ans:
+        return default
+    return ans in ("y", "yes")
+
+
+# ── subcommand implementations ────────────────────────────────────────
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    print("getbased-stack init — one-time setup")
+    print(
+        "Writes ~/.config/getbased/env, (optionally) installs + starts systemd\n"
+        "user units for rag and dashboard. Idempotent: safe to re-run."
+    )
+    print()
+
+    # 1. token (optional)
+    existing = env_file.read_env_file()
+    current_token = existing.get("GETBASED_TOKEN", "")
+    masked = "****" + current_token[-4:] if current_token else "(unset)"
+    print(f"[1/4] getbased sync token (current: {masked})")
+    token = _prompt(
+        "Paste GETBASED_TOKEN (press Enter to keep current / skip)",
+        default=current_token,
+        secret=True,
+    )
+
+    # 2. API key
+    key_path = Path(existing.get("LENS_API_KEY_FILE", str(_default_api_key_file())))
+    print(f"\n[2/4] rag API key file ({key_path})")
+    if key_path.exists():
+        print("  existing key found — reusing (init is idempotent).")
+    else:
+        print("  no key found — one will be generated on first service start.")
+    key_value = _ensure_api_key(key_path)
+    print(f"  key ready (length {len(key_value)} chars, mode 0600)")
+
+    # 3. write env file
+    print("\n[3/4] writing ~/.config/getbased/env")
+    merged = {**existing}
+    merged["GETBASED_STACK_MANAGED"] = "1"
+    if token:
+        merged["GETBASED_TOKEN"] = token
+    merged["LENS_API_KEY_FILE"] = str(key_path)
+    merged.setdefault("LENS_URL", "http://127.0.0.1:8322")
+    path = env_file.write_env_file(merged)
+    print(f"  wrote {path} (mode 0600)")
+
+    # 4. install units
+    print("\n[4/4] install systemd user units?")
+    if _yesno("install + start getbased-rag + getbased-dashboard?", default=True):
+        mgr = units.UnitManager()
+        for line in mgr.install(enable=True, start=True):
+            print(f"  {line}")
+    else:
+        print("  skipped — run `getbased-stack install` later to enable.")
+
+    # 5. linger check
+    print("\n── Post-install ──")
+    _print_linger_hint(strict=False)
+
+    # 6. MCP config pointers
+    print("\nConfigure your MCP client(s):")
+    for client in mcp_configs.SUPPORTED_CLIENTS:
+        print(f"  getbased-stack mcp-config {client}")
+
+    return 0
+
+
+def _print_linger_hint(strict: bool) -> None:
+    user = os.environ.get("USER", "")
+    if not user:
+        return
+    try:
+        linger_on = units.has_linger(user)
+    except FileNotFoundError:
+        # loginctl not on PATH (uncommon but possible in minimal containers)
+        print("  loginctl not found — cannot check linger status.")
+        return
+    gui = units.is_gui_session()
+    if linger_on:
+        print("  linger: enabled ✓ (services will survive logout + reboot)")
+        return
+    # Not on.
+    if gui:
+        # Laptop with GUI login — user will be logged in when they use this,
+        # so linger is nice-to-have, not blocking.
+        print("  linger: off (fine for laptops; services only run while you're logged in)")
+        print(f"         enable with: sudo loginctl enable-linger {user}")
+        return
+    # Headless + no linger = services die on logout. This is the "silent
+    # breakage after reboot" failure mode.
+    print("  ⚠ linger: off AND no GUI session detected (headless).")
+    print(f"    Without linger, rag + dashboard will stop as soon as this SSH session ends.")
+    print(f"    Run this once, then re-enable with `systemctl --user start getbased-rag.service`:")
+    print(f"      sudo loginctl enable-linger {user}")
+
+
+def cmd_install(args: argparse.Namespace) -> int:
+    mgr = units.UnitManager()
+    for line in mgr.install(enable=not args.no_enable, start=not args.no_start):
+        print(line)
+    _print_linger_hint(strict=False)
+    return 0
+
+
+def cmd_uninstall(args: argparse.Namespace) -> int:
+    mgr = units.UnitManager()
+    for line in mgr.uninstall():
+        print(line)
+    if args.delete_env:
+        p = env_file.env_file_path()
+        if p.exists():
+            p.unlink()
+            print(f"removed {p}")
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    # env file
+    path = env_file.env_file_path()
+    if path.exists():
+        data = env_file.read_env_file(path)
+        keys = sorted(data.keys())
+        print(f"env file: {path}  ({len(keys)} keys)")
+        for k in keys:
+            print(f"  {k}={_display_value(k, data[k])}")
+    else:
+        print(f"env file: {path} (not present — run `getbased-stack init`)")
+
+    # systemd units
+    print("\nunits:")
+    mgr = units.UnitManager()
+    try:
+        for svc in mgr.status():
+            flags = []
+            flags.append("installed" if svc["installed"] else "not installed")
+            flags.append("enabled" if svc["enabled"] else "not enabled")
+            flags.append("active" if svc["active"] else "inactive")
+            print(f"  {svc['name']}: {', '.join(flags)}")
+    except FileNotFoundError:
+        print("  systemctl not found — cannot check unit status.")
+
+    # linger
+    print()
+    _print_linger_hint(strict=False)
+    return 0
+
+
+def cmd_set(args: argparse.Namespace) -> int:
+    if "=" not in args.assignment:
+        print("usage: getbased-stack set KEY=VALUE", file=sys.stderr)
+        return 2
+    key, _, value = args.assignment.partition("=")
+    key = key.strip()
+    value = value.strip()
+    path = env_file.set_env_var(key, value)
+    print(f"{key} updated in {path}")
+    # If rag/dashboard are running, they'll pick up the change on next
+    # restart — remind the user.
+    print("restart services to apply: systemctl --user restart getbased-rag getbased-dashboard")
+    return 0
+
+
+def cmd_mcp_config(args: argparse.Namespace) -> int:
+    try:
+        snippet = mcp_configs.emit(args.client)
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        return 2
+    print(snippet, end="")
+    return 0
+
+
+def cmd_version(args: argparse.Namespace) -> int:
+    try:
+        import importlib.metadata as md
+
+        import getbased_agent_stack
+
+        print(f"getbased-agent-stack {getbased_agent_stack.__version__}")
+        for pkg in ("getbased-mcp", "getbased-rag", "getbased-dashboard"):
             try:
-                print(f"  getbased-rag {md.version('getbased-rag')}")
+                print(f"  {pkg} {md.version(pkg)}")
             except md.PackageNotFoundError:
-                print("  getbased-rag (not installed)")
-            return 0
-        except ImportError as e:
-            print(f"Missing dependency: {e}", file=sys.stderr)
-            return 1
+                print(f"  {pkg} (not installed)")
+        return 0
+    except ImportError as e:
+        print(f"Missing dependency: {e}", file=sys.stderr)
+        return 1
 
-    # Delegate to the lens CLI for everything else.
+
+def _delegate_to_lens(argv: "list[str]") -> int:
+    """Historical behavior: unknown subcommands fall through to `lens`
+    so the user can do `getbased-stack serve` / `info` / `ingest` without
+    needing to remember a separate binary."""
     try:
         from lens.cli import app as lens_app
 
         sys.argv = ["lens"] + argv
-        lens_app()
-        return 0
-    except SystemExit as e:
-        return int(e.code or 0)
+        try:
+            lens_app()
+            return 0
+        except SystemExit as e:
+            return int(e.code or 0)
     except ImportError:
-        print("getbased-rag not installed — install with `pipx install getbased-agent-stack[full]`", file=sys.stderr)
+        print(
+            "getbased-rag not installed — install with "
+            "`pipx install getbased-agent-stack[full]`",
+            file=sys.stderr,
+        )
         return 1
 
 
+# ── argparse wiring ───────────────────────────────────────────────────
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="getbased-stack",
+        description=(
+            "One-command orchestrator for the getbased agent stack. "
+            "Use `init` for first-time setup."
+        ),
+    )
+    sub = p.add_subparsers(dest="command")
+
+    sub.add_parser("init", help="Interactive one-time setup (token, API key, units).")
+
+    pi = sub.add_parser("install", help="Install + start the systemd user units.")
+    pi.add_argument("--no-enable", action="store_true", help="Copy files only; don't enable.")
+    pi.add_argument("--no-start", action="store_true", help="Enable but don't start now.")
+
+    pu = sub.add_parser("uninstall", help="Stop, disable, and remove the systemd units.")
+    pu.add_argument(
+        "--delete-env",
+        action="store_true",
+        help="Also delete ~/.config/getbased/env (keeps API key + data).",
+    )
+
+    sub.add_parser("status", help="Show env file, unit state, linger.")
+
+    ps = sub.add_parser("set", help="Upsert a single key in the shared env file.")
+    ps.add_argument("assignment", help="KEY=VALUE")
+
+    pm = sub.add_parser("mcp-config", help="Print an MCP client config snippet.")
+    pm.add_argument(
+        "client",
+        choices=mcp_configs.SUPPORTED_CLIENTS,
+        help="Which client to emit for.",
+    )
+
+    sub.add_parser("version", help="Print installed package versions.")
+
+    return p
+
+
+COMMANDS = {
+    "init": cmd_init,
+    "install": cmd_install,
+    "uninstall": cmd_uninstall,
+    "status": cmd_status,
+    "set": cmd_set,
+    "mcp-config": cmd_mcp_config,
+    "version": cmd_version,
+}
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    argv = argv if argv is not None else sys.argv[1:]
+
+    # Fast path: no args → show our help, not lens's.
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        build_parser().print_help()
+        return 0
+
+    # New commands take priority; everything else falls through to lens
+    # (preserves the old thin-wrapper behavior for `serve`, `info`, etc).
+    if argv[0] in COMMANDS:
+        args = build_parser().parse_args(argv)
+        return COMMANDS[args.command](args)
+
+    return _delegate_to_lens(argv)
+
+
 if __name__ == "__main__":
     sys.exit(main())

getbased_agent_stack/env_file.py

@@ -0,0 +1,102 @@
+"""Shell-style env file I/O for ~/.config/getbased/env.
+
+The same file format the opt-in loaders in mcp/rag/dashboard read. Kept
+intentionally tolerant — duplicate keys take last-wins, blanks and `#`
+comments survive round-trips, unknown junk is preserved (we only rewrite
+keys we explicitly care about). This lets a user hand-edit the file
+without `getbased-stack init` clobbering their comments.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Iterable
+
+
+ENV_PATH_COMMENT = """\
+# getbased shared env — read by mcp, rag, and dashboard when
+# GETBASED_STACK_MANAGED=1. Written by `getbased-stack init` and
+# `getbased-stack set`. Mode 0600.
+#
+# Lines are KEY=VALUE. Comments start with `#`. Quoted values are unwrapped.
+# Explicit env vars always win — this file only provides defaults.
+"""
+
+
+def env_file_path() -> Path:
+    """Return the XDG-correct shared env file path. Honors $XDG_CONFIG_HOME."""
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config")
+    return Path(base) / "getbased" / "env"
+
+
+def parse_env_text(text: str) -> "dict[str, str]":
+    """Parse shell-style KEY=VALUE text. Last occurrence of a key wins.
+    Intentionally permissive — malformed lines are silently skipped."""
+    out: dict[str, str] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        key = key.strip()
+        val = val.strip()
+        if len(val) >= 2 and val[0] == val[-1] and val[0] in ("'", '"'):
+            val = val[1:-1]
+        if key:
+            out[key] = val
+    return out
+
+
+def read_env_file(path: Path | None = None) -> "dict[str, str]":
+    """Read the shared env file, returning {} on missing file."""
+    p = path or env_file_path()
+    try:
+        return parse_env_text(p.read_text(encoding="utf-8"))
+    except OSError:
+        return {}
+
+
+def write_env_file(
+    values: "dict[str, str]",
+    path: Path | None = None,
+    header: str = ENV_PATH_COMMENT,
+) -> Path:
+    """Write values to the shared env file at mode 0600.
+
+    Creates parent dir if missing. Overwrites — call read_env_file first +
+    merge if you want to preserve existing keys. Values are never quoted;
+    reader handles quoting-or-not symmetrically.
+
+    Caveat: systemd's `EnvironmentFile=` parser has stricter quoting rules
+    than our Python loader — values containing whitespace or shell
+    metacharacters should be avoided. Our default values (tokens,
+    URL-safe paths) are already safe; users passing arbitrary values via
+    `getbased-stack set FOO="has spaces"` may see systemd-loaded services
+    and directly-invoked CLIs parse the value differently.
+    """
+    p = path or env_file_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    lines = [header.rstrip() + "\n\n"] if header else []
+    for k, v in values.items():
+        # Only alphanumeric + underscore are safe as env keys; anything else
+        # is a programming bug upstream, fail loud.
+        if not k or not all(c.isalnum() or c == "_" for c in k):
+            raise ValueError(f"invalid env key: {k!r}")
+        lines.append(f"{k}={v}\n")
+    p.write_text("".join(lines), encoding="utf-8")
+    os.chmod(p, 0o600)
+    return p
+
+
+def set_env_var(key: str, value: str, path: Path | None = None) -> Path:
+    """Idempotent single-key upsert. Preserves other keys."""
+    current = read_env_file(path)
+    current[key] = value
+    return write_env_file(current, path)
+
+
+def unset_env_var(key: str, path: Path | None = None) -> Path:
+    """Idempotent single-key remove. No-op if absent."""
+    current = read_env_file(path)
+    current.pop(key, None)
+    return write_env_file(current, path)

getbased_agent_stack/mcp_configs.py

@@ -0,0 +1,177 @@
+"""MCP client config snippets.
+
+Each client has its own config shape (JSON vs YAML, where to place the
+mcpServers key). All generated snippets point at the absolute path to
+`getbased-mcp` resolved via shutil.which, and carry only one env var:
+GETBASED_STACK_MANAGED=1. Everything else lives in the shared env file,
+read by the MCP process at startup.
+
+The stock Hermes snippet is the one exception — it supports richer
+configuration natively (enabled_tools, tool aliases), so we emit those.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+from typing import Callable
+
+
+SUPPORTED_CLIENTS = ("claude-desktop", "claude-code", "cursor", "cline", "hermes")
+
+# Single-token list for the Hermes snippet. Matches the tool set the MCP
+# server exposes as of getbased-mcp 0.2.2. Keep alphabetical for diff-friendliness.
+HERMES_ENABLED_TOOLS = [
+    "getbased_lens_config",
+    "getbased_list_profiles",
+    "getbased_read_profile",
+    "knowledge_activate_library",
+    "knowledge_list_libraries",
+    "knowledge_search",
+    "knowledge_stats",
+]
+
+
+def _resolve_mcp_binary(resolver: Callable[[str], "str | None"] = shutil.which) -> str:
+    """Absolute path to the `getbased-mcp` binary, or a bare-name fallback.
+    GUI-launched MCP clients (Claude Desktop, Cursor) don't inherit the
+    shell PATH, so a bare binary name often fails to resolve. We emit the
+    absolute path when we can; otherwise bare name — the caller tells the
+    user which case they got via `_resolver_warning`.
+    """
+    resolved = resolver("getbased-mcp")
+    return resolved or "getbased-mcp"
+
+
+def _resolver_warning(command: str) -> "str | None":
+    """Return a warning string if the command isn't an absolute path,
+    else None. Used by emitters to tell the user when the snippet needs
+    hand-editing to work from a GUI-launched client."""
+    if command.startswith("/") or (len(command) > 1 and command[1] == ":"):
+        return None
+    return (
+        "WARNING: `getbased-mcp` wasn't found on PATH when this snippet was\n"
+        "generated. GUI-launched MCP clients don't inherit your shell PATH;\n"
+        "replace the `command` below with an absolute path (run\n"
+        "`which getbased-mcp` in a shell where it works, paste that result)."
+    )
+
+
+def _json_block(command: str) -> "dict":
+    return {
+        "mcpServers": {
+            "getbased": {
+                "command": command,
+                "env": {"GETBASED_STACK_MANAGED": "1"},
+            }
+        }
+    }
+
+
+def _prepend_warning(banner: str, warning: "str | None") -> str:
+    if not warning:
+        return banner
+    return "// " + warning.replace("\n", "\n// ") + "\n" + banner
+
+
+def emit_claude_desktop(resolver: Callable[[str], "str | None"] = shutil.which) -> str:
+    cmd = _resolve_mcp_binary(resolver)
+    payload = _json_block(cmd)
+    banner = (
+        "// Paste into ~/Library/Application Support/Claude/claude_desktop_config.json\n"
+        "// (macOS) or %APPDATA%\\Claude\\claude_desktop_config.json (Windows).\n"
+        "// Merge with existing mcpServers if present.\n"
+    )
+    banner = _prepend_warning(banner, _resolver_warning(cmd))
+    return banner + json.dumps(payload, indent=2) + "\n"
+
+
+def emit_claude_code(resolver: Callable[[str], "str | None"] = shutil.which) -> str:
+    cmd = _resolve_mcp_binary(resolver)
+    payload = _json_block(cmd)
+    banner = (
+        "// Paste into ~/.claude/settings.json (user scope) or <project>/.mcp.json\n"
+        "// (project scope). Merge with existing mcpServers if present.\n"
+    )
+    banner = _prepend_warning(banner, _resolver_warning(cmd))
+    return banner + json.dumps(payload, indent=2) + "\n"
+
+
+def emit_cursor(resolver: Callable[[str], "str | None"] = shutil.which) -> str:
+    cmd = _resolve_mcp_binary(resolver)
+    payload = _json_block(cmd)
+    banner = "// Paste into ~/.cursor/mcp.json (merge with existing mcpServers).\n"
+    banner = _prepend_warning(banner, _resolver_warning(cmd))
+    return banner + json.dumps(payload, indent=2) + "\n"
+
+
+def emit_cline(resolver: Callable[[str], "str | None"] = shutil.which) -> str:
+    cmd = _resolve_mcp_binary(resolver)
+    payload = _json_block(cmd)
+    banner = (
+        "// Cline MCP settings. Paste into the Cline extension settings panel\n"
+        "// under 'MCP Servers' (Cursor/VSCode).\n"
+    )
+    banner = _prepend_warning(banner, _resolver_warning(cmd))
+    return banner + json.dumps(payload, indent=2) + "\n"
+
+
+def emit_hermes(resolver: Callable[[str], "str | None"] = shutil.which) -> str:
+    """Hermes uses YAML — we emit by hand (no yaml dep) since the shape
+    is trivial. Includes enabled_tools for parity with the existing
+    examples/hermes-mcp.yaml snippet.
+
+    The emitted snippet carries GETBASED_STACK_MANAGED=1 so MCP reads the
+    stack's shared env file. If you'd rather keep Hermes's config.yaml as
+    the single source of env (e.g. an existing Hermes VM that already has
+    GETBASED_TOKEN + LENS_API_KEY_FILE set explicitly), drop the env block
+    entirely. Both modes work — setdefault semantics mean explicit env
+    always wins over the shared file — but committing to one keeps
+    future debugging simpler.
+    """
+    cmd = _resolve_mcp_binary(resolver)
+    warning = _resolver_warning(cmd)
+    lines = [
+        "# Hermes Agent MCP configuration snippet for ~/.hermes/config.yaml",
+        "# See https://github.com/hermes-agent/hermes-agent for the full config schema.",
+        "# The getbased stack's shared env file carries GETBASED_TOKEN + rag URL +",
+        "# api key path; only the opt-in flag belongs in Hermes's config.",
+        "# (If your Hermes config already sets GETBASED_TOKEN / LENS_* explicitly,",
+        "# drop the env block entirely — the Python loader honors existing env.)",
+    ]
+    if warning:
+        lines.append("#")
+        for wline in warning.splitlines():
+            lines.append(f"# {wline}")
+    lines.extend(
+        [
+            "",
+            "mcp_servers:",
+            "  getbased:",
+            f"    command: {cmd}",
+            "    env:",
+            '      GETBASED_STACK_MANAGED: "1"',
+            "    enabled_tools:",
+        ]
+    )
+    for tool in HERMES_ENABLED_TOOLS:
+        lines.append(f"      - {tool}")
+    return "\n".join(lines) + "\n"
+
+
+def emit(client: str, resolver: Callable[[str], "str | None"] = shutil.which) -> str:
+    """Dispatch to the right emitter. Raises ValueError on unknown client."""
+    match client:
+        case "claude-desktop":
+            return emit_claude_desktop(resolver)
+        case "claude-code":
+            return emit_claude_code(resolver)
+        case "cursor":
+            return emit_cursor(resolver)
+        case "cline":
+            return emit_cline(resolver)
+        case "hermes":
+            return emit_hermes(resolver)
+        case _:
+            raise ValueError(
+                f"unknown client {client!r}. Supported: {', '.join(SUPPORTED_CLIENTS)}"
+            )

getbased_agent_stack/systemd/getbased-dashboard.service

@@ -0,0 +1,36 @@
+[Unit]
+Description=getbased-dashboard (web UI for rag + mcp management)
+Documentation=https://github.com/elkimek/getbased-agents/tree/main/packages/dashboard
+After=network.target getbased-rag.service
+Wants=getbased-rag.service
+
+[Service]
+Type=exec
+# Same shared env file as rag + mcp — one token, one key path, one flag.
+EnvironmentFile=-%h/.config/getbased/env
+EnvironmentFile=-/etc/default/getbased-dashboard
+Environment=GETBASED_STACK_MANAGED=1
+Environment=DASHBOARD_HOST=127.0.0.1
+Environment=DASHBOARD_PORT=8323
+ExecStart=%h/.local/bin/getbased-dashboard serve
+Restart=always
+RestartSec=5s
+
+# Hardening — the dashboard is a localhost-only HTTP server.
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=read-only
+# Needs write access for session state, activity log tailing, and writing
+# the shared env file when the user edits the token in the MCP tab.
+ReadWritePaths=%h/.local/state/getbased %h/.config/getbased
+PrivateTmp=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
+RestrictNamespaces=true
+LockPersonality=true
+RestrictRealtime=true
+
+[Install]
+WantedBy=default.target

getbased_agent_stack/systemd/getbased-rag.service

@@ -0,0 +1,41 @@
+[Unit]
+Description=getbased-rag (local RAG knowledge server)
+Documentation=https://github.com/elkimek/getbased-agents/tree/main/packages/rag
+After=network.target
+
+[Service]
+Type=exec
+# Shared env file written by `getbased-stack init` — carries GETBASED_TOKEN,
+# LENS_API_KEY_FILE, LENS_URL (and the GETBASED_STACK_MANAGED=1 opt-in
+# flag, which must be set for the Python env loader to pick up this file).
+# Optional: /etc/default/getbased-rag for system-wide overrides.
+EnvironmentFile=-%h/.config/getbased/env
+EnvironmentFile=-/etc/default/getbased-rag
+Environment=GETBASED_STACK_MANAGED=1
+Environment=LENS_HOST=127.0.0.1
+Environment=LENS_PORT=8322
+ExecStart=%h/.local/bin/lens serve
+# Restart=always (not on-failure) so a clean SIGTERM — e.g. operator stop
+# during troubleshooting — still brings the service back at the next boot.
+# Matches the failure mode that kept lens-rag.service dead for hours on
+# the Hermes VM until someone noticed.
+Restart=always
+RestartSec=5s
+
+# Hardening — the server only needs its data dir + a network socket.
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=%h/.local/share/getbased
+PrivateTmp=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
+RestrictNamespaces=true
+LockPersonality=true
+MemoryDenyWriteExecute=false  # ONNX Runtime needs W^X exception
+RestrictRealtime=true
+
+[Install]
+WantedBy=default.target

getbased_agent_stack/units.py

@@ -0,0 +1,198 @@
+"""Systemd user-unit install/uninstall/status helpers.
+
+Tests drive this through a `UnitManager` class whose shell-out boundary
+(`run_systemctl`, `run_loginctl`) can be monkeypatched. The default
+`shell` implementation uses subprocess; tests swap it for a fake that
+records calls without touching the real systemd.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from typing import Callable, Iterable
+
+# Units this package ships. Order matters for start: rag first (dashboard
+# Wants=+After= rag), so systemctl picks the right order naturally anyway.
+SERVICE_NAMES = ("getbased-rag.service", "getbased-dashboard.service")
+
+
+def _default_unit_dir() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config")
+    return Path(base) / "systemd" / "user"
+
+
+def bundled_units() -> "list[tuple[str, str]]":
+    """Return the (name, text) pairs for every service this package ships.
+    Read via importlib.resources — unit files live inside the package tree
+    so it works the same from wheel, sdist, and editable installs."""
+    results = []
+    for name in SERVICE_NAMES:
+        ref = resources.files("getbased_agent_stack") / "systemd" / name
+        results.append((name, ref.read_text(encoding="utf-8")))
+    return results
+
+
+@dataclass
+class CommandResult:
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+def _real_shell(cmd: "list[str]") -> CommandResult:
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    return CommandResult(proc.returncode, proc.stdout, proc.stderr)
+
+
+class UnitManager:
+    """Orchestrates install/uninstall/status of the bundled service units.
+
+    The shell boundary is injected so tests can assert on calls without
+    touching real systemctl. Production code constructs with defaults."""
+
+    def __init__(
+        self,
+        unit_dir: Path | None = None,
+        shell: Callable[["list[str]"], CommandResult] | None = None,
+    ) -> None:
+        self.unit_dir = unit_dir or _default_unit_dir()
+        # Resolve at call time (not class definition) so tests can
+        # monkeypatch `units._real_shell` and have new instances pick
+        # it up without needing to wire the shell through every call site.
+        self._shell = shell if shell is not None else _real_shell
+
+    # ── file operations ────────────────────────────────────────────
+
+    def install_files(self) -> "list[Path]":
+        """Copy bundled unit texts into the user unit dir. Overwrites to
+        keep install idempotent across upgrades."""
+        self.unit_dir.mkdir(parents=True, exist_ok=True)
+        written: "list[Path]" = []
+        for name, text in bundled_units():
+            dest = self.unit_dir / name
+            dest.write_text(text, encoding="utf-8")
+            written.append(dest)
+        return written
+
+    def remove_files(self) -> "list[Path]":
+        """Delete unit files from the user unit dir. No-op per file if
+        absent — idempotent."""
+        removed: "list[Path]" = []
+        for name in SERVICE_NAMES:
+            p = self.unit_dir / name
+            if p.exists():
+                p.unlink()
+                removed.append(p)
+        return removed
+
+    # ── systemctl orchestration ────────────────────────────────────
+
+    def daemon_reload(self) -> CommandResult:
+        return self._shell(["systemctl", "--user", "daemon-reload"])
+
+    def enable(self, now: bool = True) -> CommandResult:
+        args = ["systemctl", "--user", "enable"]
+        if now:
+            args.append("--now")
+        args.extend(SERVICE_NAMES)
+        return self._shell(args)
+
+    def disable(self, now: bool = True) -> CommandResult:
+        args = ["systemctl", "--user", "disable"]
+        if now:
+            args.append("--now")
+        args.extend(SERVICE_NAMES)
+        return self._shell(args)
+
+    def is_active(self, service: str) -> bool:
+        r = self._shell(["systemctl", "--user", "is-active", service])
+        return r.returncode == 0 and r.stdout.strip() == "active"
+
+    def is_enabled(self, service: str) -> bool:
+        r = self._shell(["systemctl", "--user", "is-enabled", service])
+        return r.returncode == 0 and r.stdout.strip() in ("enabled", "alias", "static")
+
+    # ── high-level ops ─────────────────────────────────────────────
+
+    def install(self, enable: bool = True, start: bool = True) -> "list[str]":
+        """Run the full install sequence. Returns a log of human-readable
+        steps for the caller to print."""
+        log: "list[str]" = []
+        written = self.install_files()
+        for p in written:
+            log.append(f"wrote {p}")
+        r = self.daemon_reload()
+        if r.returncode != 0:
+            log.append(f"daemon-reload FAILED: {r.stderr.strip()}")
+            return log
+        if enable:
+            r = self.enable(now=start)
+            if r.returncode != 0:
+                log.append(f"enable FAILED: {r.stderr.strip()}")
+            else:
+                log.append("enabled " + ", ".join(SERVICE_NAMES))
+                if start:
+                    log.append("started " + ", ".join(SERVICE_NAMES))
+        return log
+
+    def uninstall(self) -> "list[str]":
+        log: "list[str]" = []
+        r = self.disable(now=True)
+        if r.returncode != 0:
+            # Already-disabled units return non-zero on `disable --now`.
+            # Treat as advisory, keep going.
+            log.append(f"disable: {r.stderr.strip() or r.stdout.strip()}")
+        removed = self.remove_files()
+        for p in removed:
+            log.append(f"removed {p}")
+        if removed:
+            r = self.daemon_reload()
+            if r.returncode != 0:
+                log.append(f"daemon-reload FAILED: {r.stderr.strip()}")
+        return log
+
+    def status(self) -> "list[dict]":
+        """Return one dict per service with {name, installed, enabled, active}.
+        Cheap: 2 systemctl calls per service."""
+        out: "list[dict]" = []
+        for name in SERVICE_NAMES:
+            out.append(
+                {
+                    "name": name,
+                    "installed": (self.unit_dir / name).exists(),
+                    "enabled": self.is_enabled(name),
+                    "active": self.is_active(name),
+                }
+            )
+        return out
+
+
+# ── Linger detection (separate from UnitManager — independent concern) ──
+
+
+def has_linger(user: str | None = None, shell: Callable = _real_shell) -> bool:
+    """True when `loginctl show-user --property=Linger` reports `yes`.
+
+    Linger keeps user services running when the user isn't logged in —
+    required for rag/dashboard to come back after a headless reboot.
+    """
+    user = user or os.environ.get("USER", "")
+    if not user:
+        return False
+    r = shell(["loginctl", "show-user", user, "--property=Linger"])
+    return r.returncode == 0 and r.stdout.strip().lower() == "linger=yes"
+
+
+def is_gui_session() -> bool:
+    """Heuristic: does the current session have a display?
+    If not, we treat this as a headless host and require linger.
+    """
+    return bool(
+        os.environ.get("DISPLAY")
+        or os.environ.get("WAYLAND_DISPLAY")
+        or os.environ.get("XDG_SESSION_TYPE") in ("x11", "wayland")
+    )

{getbased_agent_stack-0.2.0.dist-info → getbased_agent_stack-0.4.0.dist-info}/METADATA

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: getbased-agent-stack
-Version: 0.2.0
+Version: 0.4.0
 Summary: One-command install of the full getbased agent stack — getbased-mcp + getbased-rag + getbased-dashboard
 License-Expression: GPL-3.0-only
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: getbased-mcp>=0.2.2
-Requires-Dist: getbased-rag>=0.6.1
-Requires-Dist: getbased-dashboard>=0.5.0
+Requires-Dist: getbased-mcp>=0.2.3
+Requires-Dist: getbased-rag>=0.7.1
+Requires-Dist: getbased-dashboard>=0.6.1
 Provides-Extra: full
-Requires-Dist: getbased-rag[full]>=0.6.1; extra == "full"
+Requires-Dist: getbased-rag[full]>=0.7.1; extra == "full"
 Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: httpx>=0.27; extra == "test"
@@ -19,7 +19,7 @@ Dynamic: license-file
 
 # getbased-agent-stack
 
-Meta-package bundling the full [getbased](https://getbased.health) agent stack into one install: the MCP adapter, the RAG engine, the browser dashboard, a thin discovery CLI, a hardened systemd unit, and example configs for Claude Code + Hermes.
+Meta-package bundling the full [getbased](https://getbased.health) agent stack into one install: the MCP adapter, the RAG engine, the browser dashboard, an orchestration CLI (`init` / `install` / `mcp-config`), hardened systemd units for rag + dashboard, and paste-ready configs for Claude Desktop/Code, Cursor, Cline, and Hermes.
 
 Part of the [getbased-agents monorepo](https://github.com/elkimek/getbased-agents).
 
@@ -39,36 +39,65 @@ Pulls:
 
 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
+## Quickstart — one command
 
 ```bash
-# 1. Start the RAG server — local Qdrant DB + MiniLM embedder
-lens serve                               # blocks; serves on 127.0.0.1:8322
-lens key                                 # prints the bearer token
+getbased-stack init
+```
+
+The wizard (~30 seconds):
+
+1. Prompts for your `GETBASED_TOKEN` (skip if you don't use sync)
+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
+
+Then paste one line into your MCP client:
+
+```bash
+getbased-stack mcp-config claude-desktop   # or: claude-code, cursor, cline, hermes
+```
+
+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:
+
+```bash
+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.
 
-# 2. Start the dashboard in another terminal
-getbased-dashboard serve                 # serves on 127.0.0.1:8323
+### Surviving reboot on headless hosts
 
-# 3. Open http://127.0.0.1:8323 in your browser, paste the lens key
-#    Create libraries, drag-drop files to ingest (live chunks/sec pill),
-#    run the MCP Test button to verify your agent path
+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:
 
-# 4. Wire the MCP into your AI client
-#    The dashboard's MCP tab generates paste-ready config blocks for
-#    Claude Desktop, Claude Code, Cursor, Cline, and Hermes.
+```bash
+sudo loginctl enable-linger $USER
 ```
 
-Both the RAG server and the getbased PWA talk to the same `lens` instance — point the PWA at `http://127.0.0.1:8322` under **Settings → AI → Knowledge Base → External server** and the same corpus feeds the browser chat, the dashboard, and any MCP-connected agent.
+`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.
 
-## Running as a systemd service
+### Other commands
 
 ```bash
-cp systemd/getbased-rag.service ~/.config/systemd/user/
-systemctl --user daemon-reload
-systemctl --user enable --now getbased-rag
+getbased-stack status          # env file, unit state, linger
+getbased-stack set GETBASED_TOKEN=new   # rotate the token
+getbased-stack install         # re-apply unit files after package upgrade
+getbased-stack uninstall       # stop + disable + remove units
 ```
 
-The unit is hardened (`ProtectSystem=strict`, `NoNewPrivileges`, `RestrictAddressFamilies`, etc.); run `systemd-analyze security getbased-rag` to see the score.
+### 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
 
@@ -97,6 +126,7 @@ The dashboard is likewise stateless — it proxies rag for Knowledge operations,
 |---|---|---|---|---|
 | 0.1.x | ≥0.2.0 | ≥0.1.0 | — | v1 (multi-library) |
 | 0.2.x | ≥0.2.2 | ≥0.6.0 | ≥0.5.0 | v1 (+ streaming ingest, per-library models) |
+| 0.4.x | ≥0.2.3 | ≥0.7.1 | ≥0.6.1 | v1 (+ shared env file, `getbased-stack init`, systemd units) |
 
 Bump the meta's major when sibling protocols break; bump siblings freely for normal features.
 

getbased_agent_stack-0.4.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+getbased_agent_stack/__init__.py,sha256=MgsNcLFuwotjltI3UtO_1ltIdoPW345EA-AyfV4S_-Y,281
+getbased_agent_stack/cli.py,sha256=jkk1o8DaXLooeU12vb9DZRRaeUDHeirOYxQEt8exJOc,12610
+getbased_agent_stack/env_file.py,sha256=lg_LmTspdIbmVTpsxEO4Szdv7wXtvrlCJp5lFN9xCTg,3792
+getbased_agent_stack/mcp_configs.py,sha256=1du4ChGuFv1sTR5RQ9wJgloKC6vnu8iZ0KNl8H-2MKE,6937
+getbased_agent_stack/units.py,sha256=40yvr1DbHiYkpvwKc3RCArhTD4cwwbchKZHbIrDAUNs,7577
+getbased_agent_stack/systemd/getbased-dashboard.service,sha256=ndnJlLD3eu-kWrhi9wfxHksunWNI0-BYAhzcuocPvJg,1173
+getbased_agent_stack/systemd/getbased-rag.service,sha256=wAkL2cb3kB-AzsqMsN7rO3CwzpgNJDpzH08I3pgSU-o,1468
+getbased_agent_stack-0.4.0.dist-info/licenses/LICENSE,sha256=K-IjLWkez1gJQMrlqA5zgyw8vh19mDzk4hKM9Dslmts,1024
+getbased_agent_stack-0.4.0.dist-info/METADATA,sha256=QS4voLGPSuUtMXoxKzVFXQewJAQ_cw8AR1trCyZ4UTE,6831
+getbased_agent_stack-0.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+getbased_agent_stack-0.4.0.dist-info/entry_points.txt,sha256=oIyVEEt9t6HuGncV_3y_6d0fjkY2PDOVQ2OEpyq2Q04,65
+getbased_agent_stack-0.4.0.dist-info/top_level.txt,sha256=NH7AGQBXKHxl7hzWSYDXOaIXCg_9GV3hIQbj8YR8XZQ,21
+getbased_agent_stack-0.4.0.dist-info/RECORD,,

getbased_agent_stack-0.2.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-getbased_agent_stack/__init__.py,sha256=LSo9NAptb9YiMiamzJLzIZTali0QS0bT8JU_975ddv4,281
-getbased_agent_stack/cli.py,sha256=IASj51V3gl0v9eebjuDwXfjZplqCBYlMWGCQwdGlNn4,2445
-getbased_agent_stack-0.2.0.dist-info/licenses/LICENSE,sha256=K-IjLWkez1gJQMrlqA5zgyw8vh19mDzk4hKM9Dslmts,1024
-getbased_agent_stack-0.2.0.dist-info/METADATA,sha256=4JFkTXngtk0Yhymmb6ZlUkzhQYzUzTFfVBxq9zhHBbo,5572
-getbased_agent_stack-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-getbased_agent_stack-0.2.0.dist-info/entry_points.txt,sha256=oIyVEEt9t6HuGncV_3y_6d0fjkY2PDOVQ2OEpyq2Q04,65
-getbased_agent_stack-0.2.0.dist-info/top_level.txt,sha256=NH7AGQBXKHxl7hzWSYDXOaIXCg_9GV3hIQbj8YR8XZQ,21
-getbased_agent_stack-0.2.0.dist-info/RECORD,,