Helm

A local project dashboard that discovers, analyzes, and tracks all your git repositories. Single binary, runs on login, accessible at http://localhost:7777.

Docs

• docs/deployment.md VPS deployment with systemd + Caddy
• docs/operations.md day-2 operations (status, logs, deploys, rollback)
• docs/troubleshooting.md common issues and fixes
• docs/backup-and-restore.md backup and restore procedures
• docs/security.md hardening baseline
• docs/central-sync-architecture.md central sync architecture and rollout

Quick Start

make build
bin/helm

Open http://localhost:7777 and click "Scan Projects" to discover your repos.

Install as Login Agent

make install
launchctl load ~/Library/LaunchAgents/com.helm.dashboard.plist

Run Modes

Local Development

# Terminal 1: Go backend
go run ./cmd/dashboard

# Terminal 2: Frontend dev server (with hot reload + API proxy)
cd frontend && pnpm dev

Open http://localhost:5173 for the dev frontend (proxies API to :7777).

Local Single-Binary

make build
bin/helm

VPS (Systemd + Caddy)

See docs/deployment.md.

Build

make build    # builds frontend + Go binaries into bin/
make clean    # removes build artifacts

make build also builds bin/helm-agent.

Configuration

Flag	Default	Description
-port	7777	HTTP server port
-scan-root	~/Developer	Root directory to scan for git repos

Data stored in ~/Library/Application Support/helm/db.sqlite.

Environment Variable Matrix

Variable	Scope	Required	Purpose
HELM_GITHUB_TOKEN / GITHUB_TOKEN	server	optional	GitHub API access for remote sync/planning
HELM_ALLOWED_ORIGINS	server	recommended	Comma-separated CORS origins (* by default)
HELM_SYNC_READ_TOKEN	server	recommended (internet-facing)	Protects GET /api/sync/agents* endpoints
HELM_SYNC_BATCH_RETENTION_DAYS	server	optional	Idempotency batch retention (default 30)
HELM_ALERT_WEBHOOK_URL	server	optional	Webhook for agent sync errors
GITHUB_OAUTH_CLIENT_ID	server	optional	GitHub OAuth sign-in
GITHUB_OAUTH_CLIENT_SECRET	server	optional	GitHub OAuth sign-in
HELM_SESSION_SECRET	server	recommended	Stable session signing secret
HELM_ALLOWED_USERS	server	optional	Comma-separated GitHub usernames allowed to sign in
HELM_PORT	server (systemd env file)	required on VPS	Server listen port
HELM_SCAN_ROOT	server (systemd env file)	required on VPS	Server scan root path

Agent runtime variables are documented in packaging/agent/linux/agent.env.example.

Central Sync Agent Setup (Phase 1)

Run one agent sync cycle manually:

bin/helm-agent --server-url http://your-helm-server:7777 --scan-root ~/Developer --once

API and architecture details: docs/central-sync-architecture.md.

macOS (launchd)

Template:

• packaging/agent/macos/com.helm.agent.plist.template

Steps:

1. Copy the template to ~/Library/LaunchAgents/com.helm.agent.plist.
2. Replace {{SERVER_URL}}, {{SCAN_ROOT}}, and {{INTERVAL}} (example: 10m).
3. Load it:

launchctl unload ~/Library/LaunchAgents/com.helm.agent.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.helm.agent.plist

Linux (systemd user service)

Files:

• packaging/agent/linux/helm-agent.service
• packaging/agent/linux/agent.env.example

Steps:

1. Copy env example to ~/.config/helm/agent.env and set values.
2. Copy service file to ~/.config/systemd/user/helm-agent.service.
3. Enable and start:

systemctl --user daemon-reload
systemctl --user enable --now helm-agent.service

Windows (Task Scheduler)

Script:

• packaging/agent/windows/install-agent-task.ps1

Example:

powershell -ExecutionPolicy Bypass -File .\packaging\agent\windows\install-agent-task.ps1 -ServerUrl "http://your-helm-server:7777" -ScanRoot "C:\Users\you\Developer" -Interval "10m"

Production Hardening Notes

Recommended for public/server deployments:

1. Set HELM_ALLOWED_ORIGINS to your exact UI origin(s), not *.
2. Set HELM_SYNC_READ_TOKEN to protect sync read endpoints.
3. Keep HELM_SYNC_BATCH_RETENTION_DAYS at a bounded value (for example 30).
4. Set HELM_ALERT_WEBHOOK_URL for external alerting (Slack/webhook bridge).

Expanded hardening checklist: docs/security.md.

Admin token UX:

• Use Settings → Sync Admin Token to save/clear/test access in-browser.

Webhook payload example (HELM_ALERT_WEBHOOK_URL):

{
  "event": "agent_sync_error",
  "agent_id": "3",
  "agent_name": "mbp14",
  "platform": "darwin",
  "hostname": "mbp14.local",
  "message": "snapshot upload failed: request failed (502)",
  "timestamp": "2026-02-12T20:40:15Z",
  "text": "Helm agent error on mbp14 (mbp14.local): snapshot upload failed: request failed (502)"
}