helmdeck

Today's helmdeck install ran a full 6-step code-edit loop (clone, read, patch, test, commit, push) on gpt-oss-120b for $0.07. The same loop on Cursor or Claude Code direct via Sonnet would have cost $0.30+. Same outcome, ~5× cheaper — and the "expensive" stack isn't even the most expensive option.

Most browser agents require GPT-4o or Claude Sonnet to work reliably. Helmdeck is built for the other 99% of deployments — local 7B models, air-gapped environments, and teams that can't send credentials to a cloud API. It wraps every browser, desktop, git, and code action into a single typed JSON call that even a small model can fill in correctly. The numbers above are the consequence: when packs absorb the work the LLM would otherwise burn tokens rediscovering, cheap or local models do agentic work that frontier-model APIs charge 10× more for.

A 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.

📊 Full per-task comparison with reproduction recipe at https://helmdeck.dev/explanation/why-helmdeck. These are one maintainer's findings; we welcome community reproductions.

Why this exists

Smart 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.

Three audiences specifically:

• Self-hosted AI teams who can't leave their VPC and need MCP-native infra that doesn't phone home.
• The LocalLLaMA / Ollama crowd running 7B–30B models — pack contracts keep small models reliable where open-ended tool surfaces fail.
• 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).

Status

v0.22.0 shipped — agents that work on free models, with memory. The release closes ADRs 047–050:

• 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.
• 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.
• Intent decomposition (ADR 049) — helmdeck.plan turns a multi-action prompt into an ordered, pipeline-aware step plan plus a rewritten_prompt.
• 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.

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 MCP Registry as io.github.tosin2013/helmdeck for one-line install in registry-aware clients. Phases 1–6.5 are complete; the current milestone is v1.0 — Kubernetes & GA (Phase 7), with backlog materialised as GitHub issues tagged good first issue and help wanted.

• 49 ADRs in docs/adrs/ — every architectural decision with PRD back-references
• Task breakdown in docs/TASKS.md — ~85 tasks across 8 phases with critical path
• GitHub milestones in docs/MILESTONES.md — drop-in issue checklists with current ship state
• Pack reference in docs/PACKS.md — every shipped pack's input/output contract

Quick start

git clone https://github.com/tosin2013/helmdeck
cd helmdeck
./scripts/install.sh

That'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.

✓ helmdeck is up

  URL:       http://localhost:3000
  Username:  admin
  Password:  <generated; printed once — save it now>

Useful flags:

• ./scripts/install.sh --reset — tear down, regenerate secrets, reinstall (new admin password)
• ./scripts/install.sh --no-build — skip build steps, just bring the stack up
• ./scripts/install.sh --help — full flag reference

Or via make: make install.

Connect a client

A running stack is just the platform — the value is packs called by an agent. Wire one of the supported MCP clients to your fresh install:

Once a client is connected, work through the pack-demo-playbook.md — 20+ copy-pasteable prompts that exercise every pack. The per-pack reference covers each pack's contract, error codes, and chained workflows.

Advanced: manual setup

If you'd rather drive each step yourself instead of running the install script:

# 1. Build the Management UI bundle (needs Node 20+)
make web-deps && make web-build

# 2. Build the control-plane binary with the UI embedded
make build

# 3. Run the control plane with admin credentials
HELMDECK_JWT_SECRET=$(openssl rand -hex 32) \
HELMDECK_VAULT_KEY=$(openssl rand -hex 32) \
HELMDECK_ADMIN_PASSWORD=changeme \
./bin/control-plane

Or use the Compose stack directly (control plane + Garage object store + bundled init):

cp deploy/compose/.env.example deploy/compose/.env.local
# …edit deploy/compose/.env.local and fill in real secrets…
docker compose -f deploy/compose/compose.yaml --env-file deploy/compose/.env.local up -d

Logging in to the Management UI

The login endpoint accepts a static admin password set via the HELMDECK_ADMIN_PASSWORD env var on the control plane process. Suitable for the dev / single-node Compose tier; OIDC SSO for production deployments lands in a later phase.

To change the password: stop the control plane, set HELMDECK_ADMIN_PASSWORD to the new value, and restart. There is no in-UI "change password" flow today — the password is managed out-of-band by whichever orchestrator runs the control plane (Compose, systemd, Kubernetes Secret, etc.).

If HELMDECK_ADMIN_PASSWORD is unset, the login endpoint returns 503 login_disabled. The control plane still runs and the API still works — operators can mint a JWT directly via the CLI:

./bin/control-plane -mint-token=alice -mint-token-scopes=admin -mint-token-ttl=12h

The minted token can be pasted into any tool that speaks Authorization: Bearer <token>.

Production note: the static-password path uses constant-time comparison so it's safe against timing attacks, but it's still a shared secret that has to be rotated by hand. For production deployments with multiple operators, OIDC SSO via your existing identity provider is the right answer — see the Phase 6 follow-up roadmap.

Architecture at a glance