Skip to main content

How-to guides

Problem-solving recipes. Each guide assumes you already have helmdeck installed and answers a single, focused question: how do I do X?

Operations​

  • Troubleshoot the install — symptom-first table for the known sharp edges in the install path: 502 on first session, GHCR pull failures, lost admin password, sidecar build hangs, blank UI panels, accidental --reset.
  • Upgrade helmdeck — pre-flight checklist, in-place Compose-stack upgrade (git pull && make install), schema-migration handling, post-upgrade validation, and rollback. Previews the Helm/Kubernetes path coming with v1.0.
  • Register helmdeck with your MCP client — one-line install via the official MCP Registry (io.github.tosin2013/helmdeck), stdio config snippet for any client, smoke test, and per-client lookup table covering Claude Code, Claude Desktop, OpenClaw, Gemini CLI, Hermes Agent, and Cursor.
  • Watch the agent live via noVNC — open a browser tab into a running sidecar and watch what the agent sees in real time. Quick-start desktop-mode session creation, three reachability paths (baas-net / port-forward / reverse-proxy with HELMDECK_VNC_PUBLIC_BASE), agent-status overlay, and security caveats. Useful for debugging vision packs and verifying desktop packs.
  • Manage credentials in the vault — create / grant / use / audit credentials of all 5 supported types (login, cookie, api_key, oauth, ssh). Worked examples for GitHub PAT, SSH deploy keys, Ghost Admin keys, ElevenLabs, site logins, and OAuth bundles.
  • Configure LLM providers — register provider keys (Anthropic, OpenAI, Gemini, OpenRouter, Ollama, Groq, Mistral, Deepseek), list/rotate/test/delete via REST, configure fallback chains with the three closed-set triggers (rate_limit, timeout, error), and read the T607 success-rate panel.
  • Inspect audit logs — query patterns for the three audit tables (audit_log, provider_calls, credential_usage_log) with SQL examples for compliance exports, failure-pattern analysis, fallback-rate monitoring, and cost approximation.
  • Build a subprocess pack — drop an executable + YAML manifest into $HELMDECK_COMMAND_PACKS_DIR to expose a typed pack in any language. Covers the subprocess protocol, manifest field reference, and security notes.
  • Use the helmdeck CLI — helmdeck pack list/install/uninstall/marketplace/installed. Wraps the marketplace REST endpoints with HELMDECK_URL + HELMDECK_TOKEN env-var auth, mirrors the Management UI's /marketplace panel for terminal use.

Routing, memory & orchestration (v0.22.0)​

The orchestration meta-packs and the memory/context subsystems shipped in v0.22.0 (ADRs 047-050):

  • Route a request and read gap warnings — use helmdeck.route + helmdeck://routing-guide to pick the right pack/pipeline, read suggested_inputs pre-fills, and act on the gap_warning when nothing fits.
  • Decompose a multi-step request — helmdeck.plan turns a multi-action prompt into ordered steps[] + a rewritten_prompt; when to iterate steps vs. feed the rewritten prompt back.
  • Run orchestration packs on free models — the LLM context manager (ADR 050): per-model budgets, catalog compaction, the compaction output field, and diagnosing empty plans.
  • Store agent facts — helmdeck.memory_store / helmdeck.memory_forget and the helmdeck://my-memory read surface: write, read, forget durable user facts across sessions.
  • Expose helmdeck memory to OpenClaw — wire the OpenClaw memory bridge so an agent's memory_search hits helmdeck's stored facts.
  • OpenClaw memory corpus bridge — the QMD corpus endpoint that backs OpenClaw memory_search (ADR 048 PR #3).

Pipelines​

  • When a pipeline fails — read failure_class (caller_fixable / pack_bug / transient / state_changed) + failure_reason, and recover with helmdeck__pipeline-rerun.

Client integrations​

Wire helmdeck into your MCP-capable client of choice:

Sidecars​

Extend helmdeck's sandboxed execution surface:

What goes here​

How-to guides are problem-oriented. Unlike tutorials, they assume the reader has prior context and is looking for the shortest path between a real problem and its solution. They list trade-offs but don't teach foundations — that's what tutorials are for.