{
  "markdown": "# helmdeck\n\n> Today's helmdeck install ran a full 6-step code-edit loop (clone, read, patch,\n> test, commit, push) on `gpt-oss-120b` for **$0.07**. The same loop on Cursor\n> or Claude Code direct via Sonnet would have cost **$0.30+**. Same outcome,\n> ~5× cheaper — and the \"expensive\" stack isn't even the most expensive option.\n\n| Workflow | Frontier-model approach | Helmdeck (gpt-oss-120b) |\n|---|---|---|\n| Browser scrape + GitHub comment | $0.25 (Anthropic Computer Use) | **$0.005** |\n| Code edit loop (6 steps) | $0.35 (Cursor / Aider) | **$0.07** |\n| Multi-step browser test | $0.20 (Browser-use NL) | **$0.03** |\n| PDF → structured Markdown | $1.00 (naive Sonnet vision) | **$0.003** |\n\n> Most browser agents require GPT-4o or Claude Sonnet to work reliably.\n> Helmdeck is built for the other 99% of deployments — **local 7B models,\n> air-gapped environments, and teams that can't send credentials to a\n> cloud API.** It wraps every browser, desktop, git, and code action\n> into a single typed JSON call that even a small model can fill in correctly.\n> The numbers above are the consequence: when packs absorb the work the\n> LLM would otherwise burn tokens rediscovering, cheap or local models do\n> agentic work that frontier-model APIs charge 10× more for.\n\nA self-hosted, containerized platform for AI agents, exposed as **Capability Packs** — schema-validated, one-shot JSON tools — and native MCP. The defining metric is **≥90% pack success on 7B–30B-class open-weight models**, something no frontier-targeting competitor is optimizing for.\n\n> 📊 **Full per-task comparison** with reproduction recipe at <https://helmdeck.dev/explanation/why-helmdeck>. These are one maintainer's findings; we welcome [community reproductions](https://helmdeck.dev/blog).\n\n## Why this exists\n\nSmart models thrive on bash and a README. Weak models stall on open-ended interfaces. Helmdeck closes that gap by hiding browser sessions, desktop actions, credentials, and multi-step workflows behind single typed REST / MCP calls.\n\nThree audiences specifically:\n\n- **Self-hosted AI teams** who can't leave their VPC and need MCP-native infra that doesn't phone home.\n- **The LocalLLaMA / Ollama crowd** running 7B–30B models — pack contracts keep small models reliable where open-ended tool surfaces fail.\n- **Security-sensitive orgs** who need agents to log into SaaS apps without the model ever seeing a credential (vault-backed placeholder tokens + MCP-level audit).\n\n## Status\n\n**v0.22.0 shipped** — *agents that work on free models, with memory.* The release closes ADRs 047–050:\n\n- **Pipeline routing + routing memory (ADR 047)** — the `helmdeck.route` meta-pack recommends the best pack/pipeline for an intent (with structured gap warnings when nothing fits), backed by per-caller learned defaults surfaced through the `helmdeck://routing-guide` and `helmdeck://my-defaults` MCP resources and a Routing Memory management UI.\n- **Memory write surface + OpenClaw bridge (ADR 048)** — `helmdeck.memory_store` persists durable user facts (read back via `helmdeck://my-memory`), an optional embedding sidecar powers OpenClaw's `memory_search`, and a QMD corpus bridge exposes helmdeck memory to OpenClaw.\n- **Intent decomposition (ADR 049)** — `helmdeck.plan` turns a multi-action prompt into an ordered, pipeline-aware step plan plus a `rewritten_prompt`.\n- **LLM context manager (ADR 050)** — `internal/llmcontext` compacts catalog-heavy prompts to fit small-model context budgets (tiered per-model budgets, cascading select + lexical rank, optional two-pass filter), surfaced through `helmdeck://context-budgets` and `helmdeck://my-plans`.\n\n**57 capability packs** ship in the control-plane binary (47 without an AI gateway configured), alongside **21 built-in pipelines**, a community pack **marketplace** (`helmdeck pack install <name>`), and operator-supplied `cmd.*` subprocess packs. Earlier headline features remain: end-to-end content chaining (image.generate auto-feeds podcast/slides/blog covers), the `helmdeck://image-models` MCP resource, image-mode install (`./scripts/install.sh --image-mode`), and the Pack Test Runner UI. Helmdeck is published to the [official\nMCP Registry](https://registry.modelcontextprotocol.io/) as\n`io.github.tosin2013/helmdeck` for one-line install in registry-aware\nclients. Phases 1–6.5 are complete; the current milestone is **v1.0 — Kubernetes & GA** (Phase 7), with backlog\nmaterialised as GitHub issues tagged\n[`good first issue`](https://github.com/tosin2013/helmdeck/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)\nand [`help wanted`](https://github.com/tosin2013/helmdeck/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).\n\n- **49 ADRs** in [`docs/adrs/`](docs/adrs/) — every architectural decision with PRD back-references\n- **Task breakdown** in [`docs/TASKS.md`](docs/TASKS.md) — ~85 tasks across 8 phases with critical path\n- **GitHub milestones** in [`docs/MILESTONES.md`](docs/MILESTONES.md) — drop-in issue checklists with current ship state\n- **Pack reference** in [`docs/PACKS.md`](docs/PACKS.md) — every shipped pack's input/output contract\n\n## Quick start\n\n```sh\ngit clone https://github.com/tosin2013/helmdeck\ncd helmdeck\n./scripts/install.sh\n```\n\nThat's it. The script runs preflight checks (`docker`, `node` ≥20, `go` ≥1.26, `make`, `openssl`, `curl`) with platform-aware install hints, generates fresh secrets into `deploy/compose/.env.local` (chmod 600), builds the Management UI bundle, the Go binaries, and the browser sidecar image, brings the Compose stack up, and prints the URL plus a freshly generated admin password.\n\n```text\n✓ helmdeck is up\n\n  URL:       http://localhost:3000\n  Username:  admin\n  Password:  <generated; printed once — save it now>\n```\n\nUseful flags:\n\n- `./scripts/install.sh --reset` — tear down, regenerate secrets, reinstall (new admin password)\n- `./scripts/install.sh --no-build` — skip build steps, just bring the stack up\n- `./scripts/install.sh --help` — full flag reference\n\nOr via `make`: `make install`.\n\n### Connect a client\n\nA running stack is just the platform — the value is **packs called by an\nagent**. Wire one of the supported MCP clients to your fresh install:\n\n| Client | Status | Setup guide |\n|---|---|---|\n| **OpenClaw** | ✅ validated end-to-end | [`docs/integrations/openclaw.md`](docs/integrations/openclaw.md) |\n| Claude Code | 🟡 documented | [`docs/integrations/claude-code.md`](docs/integrations/claude-code.md) |\n| Claude Desktop | 🟡 documented | [`docs/integrations/claude-desktop.md`](docs/integrations/claude-desktop.md) |\n| Gemini CLI | 🟡 documented | [`docs/integrations/gemini-cli.md`](docs/integrations/gemini-cli.md) |\n| Hermes Agent | 🟡 documented | [`docs/integrations/hermes-agent.md`](docs/integrations/hermes-agent.md) |\n\nOnce a client is connected, work through the\n[`pack-demo-playbook.md`](docs/integrations/pack-demo-playbook.md) — 20+\ncopy-pasteable prompts that exercise every pack. The\n[per-pack reference](https://helmdeck.dev/reference/packs/) covers each\npack's contract, error codes, and chained workflows.\n\n### Advanced: manual setup\n\nIf you'd rather drive each step yourself instead of running the install script:\n\n```sh\n# 1. Build the Management UI bundle (needs Node 20+)\nmake web-deps && make web-build\n\n# 2. Build the control-plane binary with the UI embedded\nmake build\n\n# 3. Run the control plane with admin credentials\nHELMDECK_JWT_SECRET=$(openssl rand -hex 32) \\\nHELMDECK_VAULT_KEY=$(openssl rand -hex 32) \\\nHELMDECK_ADMIN_PASSWORD=changeme \\\n./bin/control-plane\n```\n\nOr use the Compose stack directly (control plane + Garage object store + bundled init):\n\n```sh\ncp deploy/compose/.env.example deploy/compose/.env.local\n# …edit deploy/compose/.env.local and fill in real secrets…\ndocker compose -f deploy/compose/compose.yaml --env-file deploy/compose/.env.local up -d\n```\n\n## Logging in to the Management UI\n\nThe login endpoint accepts a static admin password set via the\n`HELMDECK_ADMIN_PASSWORD` env var on the control plane process.\nSuitable for the dev / single-node Compose tier; OIDC SSO for\nproduction deployments lands in a later phase.\n\n| Setting | Default | Override |\n| --- | --- | --- |\n| Username | `admin` | `HELMDECK_ADMIN_USERNAME` env var |\n| Password | *(none — UI login disabled)* | `HELMDECK_ADMIN_PASSWORD` env var (required) |\n| Session length | 12 hours | Hardcoded in `internal/api/auth_login.go` |\n\n**To change the password:** stop the control plane, set\n`HELMDECK_ADMIN_PASSWORD` to the new value, and restart. There is\nno in-UI \"change password\" flow today — the password is managed\nout-of-band by whichever orchestrator runs the control plane\n(Compose, systemd, Kubernetes Secret, etc.).\n\n**If `HELMDECK_ADMIN_PASSWORD` is unset**, the login endpoint\nreturns `503 login_disabled`. The control plane still runs and the\nAPI still works — operators can mint a JWT directly via the CLI:\n\n```sh\n./bin/control-plane -mint-token=alice -mint-token-scopes=admin -mint-token-ttl=12h\n```\n\nThe minted token can be pasted into any tool that speaks\n`Authorization: Bearer <token>`.\n\n**Production note:** the static-password path uses constant-time\ncomparison so it's safe against timing attacks, but it's still a\nshared secret that has to be rotated by hand. For production\ndeployments with multiple operators, OIDC SSO via your existing\nidentity provider is the right answer — see the Phase 6 follow-up\nroadmap.\n\n## Architecture at a glance\n\n- **Sidecar pattern** — browser runs in its own container, never embedded in the agent (ADR 001)\n- **Golang control plane** — single static binary, distroless image, embeds the React UI (ADR 002)\n- **Capability Packs** — the primary product surface; user-authorable via Go or WASM (ADRs 003, 012, 024)\n- **OpenAI-compatible AI gateway** — Anthropic, Gemini, OpenAI, Ollama, Deepseek with encrypted keys + fallback routing (ADR 005)\n- **MCP server registry** — stdio/SSE/WebSocket transports; built-in MCP server auto-derived from the pack catalog (ADR 006)\n- **Credential vault** — AES-256-GCM with placeholder-token injection; agents never see secrets (ADR 007)\n- **Dual-tier deployment** — Docker Compose for dev/single-node, Helm chart for Kubernetes production (ADRs 009, 010, 011)\n- **First-class MCP clients** — Claude Code, Claude Desktop, OpenClaw, Gemini CLI via a single shared `helmdeck-mcp` bridge binary (ADRs 025, 030)\n- **Bundled object store** — [Garage](https://garagehq.deuxfleurs.fr/) ships in the Compose stack as the default artifact backend; pluggable to any S3-compatible endpoint (AWS S3, R2, B2, SeaweedFS) for production (ADR 031)\n\n## Built-in Capability Packs\n\n57 packs ship in the box (47 without an AI gateway configured). Each one hides a multi-step workflow\nbehind a single typed JSON-Schema call so weak open-weight models\ncan drive it as reliably as frontier models. The full input/output\ncontract for every pack lives in [`docs/PACKS.md`](docs/PACKS.md).\nThe highlights:\n\n| Pack | What it hides |\n| :--- | :--- |\n| **Browser & web** | |\n| `browser.screenshot_url` | Session lifecycle, navigation, render wait, cleanup |\n| `browser.interact` | Deterministic multi-step CDP (navigate, click, type, scroll, screenshot, assert_text) — no LLM needed |\n| `web.scrape` / `web.scrape_spa` | Firecrawl-backed markdown scrape OR schema-driven SPA extraction |\n| `web.test` | Natural-language browser tests via Playwright MCP + LLM loop |\n| `research.deep` | Multi-source Firecrawl search + per-source scrape + LLM synthesis with inline citations |\n| `content.ground` | Parses a markdown file for claims, finds authoritative sources, inserts real `[link](url)` citations in place |\n| **Document & vision** | |\n| `slides.render` | Marp + Chromium + format flags |\n| `slides.narrate` | Narrated MP4 video (ElevenLabs TTS per slide) + YouTube engagement metadata + sidecar SRT captions + structured `validation` field (default-on post-step) |\n| `av.validate` | Structured AV-artifact validation (faststart, codec pin, packet contiguity, RMS sweep, LUFS, duration parity, SRT format) — default-on as a post-step on `slides.narrate`/`podcast.generate`; standalone for ad-hoc checks |\n| `doc.parse` | Docling layout-aware parse — PDF tables, multi-format, OCR fallback |\n| `doc.ocr` | Tesseract fallback for simple images |\n| `desktop.run_app_and_screenshot` | Xvfb + xdotool + scrot + window focus |\n| `vision.click_anywhere` | Native computer-use routing (Anthropic/OpenAI/Gemini schemas) with JSON-prompt fallback for Ollama/Deepseek |\n| `vision.extract_visible_text` / `vision.fill_form_by_label` | Screenshot → vision model → action loop |\n| **Code edit loop** | |\n| `repo.fetch` / `repo.push` | SSH key selection from vault, `known_hosts`, key shred-on-exit; envelope returns `tree`/`readme`/`entrypoints`/`signals` so agents orient on the first turn |\n| `repo.map` | Aider-style structural symbol map under a token budget |\n| `fs.read` / `fs.write` / `fs.patch` / `fs.list` / `fs.delete` | Path-safe file ops inside a clone |\n| `cmd.run` | Run an arbitrary command in a clone path |\n| `git.commit` / `git.diff` / `git.log` | Stage + commit + review changes attributed to `helmdeck-agent` |\n| **GitHub** | |\n| `github.create_issue` / `github.list_issues` / `github.list_prs` / `github.post_comment` / `github.create_release` / `github.search` | Vault-stored PAT, never visible to the agent |\n| **Language sidecars** | |\n| `python.run` | CPython 3 + pytest + ruff + mypy in a Python sidecar image |\n| `node.run` | Node 20 LTS + npm + pnpm + yarn + tsc in a Node sidecar image |\n| **HTTP & credentials** | |\n| `http.fetch` | Placeholder-token egress: `${vault:NAME}` substitution in URL/headers/body |\n\nSee ADRs 014–036 for per-pack contracts and\n[`docs/SIDECAR-LANGUAGES.md`](docs/SIDECAR-LANGUAGES.md) for the\nrunbook on adding new language sidecars (Rust, Go, Ruby, etc.).\nThe contribution guide in [`CONTRIBUTING.md`](CONTRIBUTING.md)\nwalks through writing your own pack — the most useful contributions\nright now are SaaS API wrappers (Slack, Linear, Stripe, Notion, etc.).\n\n## License\n\nLicensed under the [Apache License, Version 2.0](LICENSE). See\n[`NOTICE`](NOTICE) for attribution to bundled and depended-upon\nprojects, and [`CONTRIBUTING.md`](CONTRIBUTING.md) for the\ncontribution guide and the SPDX header convention.\n\nBy submitting a pull request you agree to license your contribution\nunder the same terms (Apache 2.0 Section 5 covers the contribution\ngrant — there's no separate CLA).\n\n## Author\n\n[Tosin Akinosho](mailto:tosin.akinosho@gmail.com) ([@tosin2013](https://github.com/tosin2013))\n",
  "bytes": 14561,
  "sha": "1727de013c148b4f04811dd35e711906ab8a30b7da0d007b96d96c42b4ec31af",
  "repo_slug": "tosin2013/helmdeck",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tosin2013_helmdeck_9acf9a1b/readme"
}