Helmdeck

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 ), 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:

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 .

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

• Sidecar pattern — browser runs in its own container, never embedded in the agent (ADR 001)
• Golang control plane — single static binary, distroless image, embeds the React UI (ADR 002)
• Capability Packs — the primary product surface; user-authorable via Go or WASM (ADRs 003, 012, 024)
• OpenAI-compatible AI gateway — Anthropic, Gemini, OpenAI, Ollama, Deepseek with encrypted keys + fallback routing (ADR 005)
• MCP server registry — stdio/SSE/WebSocket transports; built-in MCP server auto-derived from the pack catalog (ADR 006)
• Credential vault — AES-256-GCM with placeholder-token injection; agents never see secrets (ADR 007)
• Dual-tier deployment — Docker Compose for dev/single-node, Helm chart for Kubernetes production (ADRs 009, 010, 011)
• First-class MCP clients — Claude Code, Claude Desktop, OpenClaw, Gemini CLI via a single shared helmdeck-mcp bridge binary (ADRs 025, 030)
• Bundled object store — Garage 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)

Built-in Capability Packs

57 packs ship in the box (47 without an AI gateway configured). Each one hides a multi-step workflow behind a single typed JSON-Schema call so weak open-weight models can drive it as reliably as frontier models. The full input/output contract for every pack lives in docs/PACKS.md. The highlights:

| av.validate | Structured AV-artifact validation (faststart, codec pin, packet contiguity, RMS swee