hephaestus

Spin up ephemeral Kubernetes environments per branch / PR / experiment. Cluster-agnostic. Free tools only. AI-driven CLI surface.

CLI binary is heph (and heph-mcp for the MCP server).

what it does

heph create pr-156 --target backend --source api:~/wt/api-PR156

→ writes .heph/envs/pr-156.yaml overlay (target: backend) → auto-creates a k3d cluster + embedded registry if none (~14s) → resolves the backend target's closure (services + manifests + charts + jobs) → builds source-built service images, pushes, applies → deploys infra services (postgres etc.) before pre-deploy jobs → wires a Cloudflare quick-tunnel; prints https://<random>.trycloudflare.com → syncs your source dir into the pod (sub-second hot reload) → heartbeats TTL so an in-cluster janitor cleans it up after 1h idle → tears itself down if you rm -rf the source dir

install

prerequisites:

tool	required	for
bun ≥ 1.2	yes	runtime
docker	yes	image builds
kubectl	yes	apply manifests
k3d ≥ 5.6	only for cluster: auto / k3d:*	local cluster + registry
helm	only if you use charts: (helm releases)	helm install/upgrade

setup:

git clone <this-repo>
cd hephaestus/heph
bun install
bun link            # makes `heph` and `heph-mcp` available on PATH

verify:

heph --help

quickstart

create heph.yaml in your project root (see heph/examples/heph.yaml):

project: myapp
cluster: auto
registry: auto
share: auto
ttl: 1h

image:
  base: oven/bun:1.2-alpine
  setup: ["sh -c '[ -f package.json ] && bun install --no-save || true'"]

services:
  api:
    kind: service
    source: ./services/api
    port: 3000
    cmd: [bun, run, server.ts]
    dependencies: [postgres]
    env:
      DATABASE_URL: postgres://app:app@postgres:5432/app?sslmode=disable
  postgres:
    kind: service
    image: postgres:16-alpine
    port: 5432
    env: { POSTGRES_USER: app, POSTGRES_PASSWORD: app, POSTGRES_DB: app }

targets:
  default:
    services: [api, postgres]

then:

heph create dev --target default
heph url dev          # https://<random>.trycloudflare.com
heph status dev       # pods, ttl, expires, url
heph logs dev api -f
heph shell dev api
heph down dev

docs

read in order. each file is one topic, AI-readable.

00-overview	what + why
01-stack	tools used (and rejected)
02-config-schema	base + overlay model, merge rules
03-cli	every command + flag
04-lifecycle	TTL, heartbeat, janitor, source-watcher
05-sharing	the five share modes
06-gotchas	traps caught in the spike
07-spike-results	timing numbers
08-next-steps	what's done, what's deferred
09-research-summary	landscape + decisions log

what's in the box

heph/                  CLI source (laptop-bound: build, sync, CR ops)
  src/
    cli/               command dispatch + each verb
    config/            schema (zod) + merge engine + global config
    cluster/           k3d auto-create / BYO context
    registry/          k3d push/pull split discovery
    build/             Dockerfile rendering, content-hash skip
    sync/              fs.watch → mtime-diff → tar → kubectl exec
    lifecycle/         TTL parsing, heartbeat (patches CR.spec.lastSeen)
    operator/          CR builder + apply + detection
    bootstrap/         tier-1 cluster reconcile (cert-manager, reflector)
    tls/               TLS provider × CA registry + auto-injection
    template/          ${var} substitution for manifests
    manifests/         raw + sealed-secret + sops + age apply paths (tier-1 + tier-2)
    charts/            helm chart apply path (tier-1 + tier-2)
    services/          apply-infra: prebuilt-image runtime services
    jobs/              pre/post-deploy Job render + apply
    slug/              readable + random slug generators
    mcp/server.ts      MCP server: one tool per CLI verb
  examples/heph.yaml   reference config
operator/              NestJS+Bun in-cluster operator
  src/
    environment/       CRD types + watch loop + reconcile
    render/            pure-fn manifest renderer
    apply/             server-side apply via k8s API
    share/             cloudflared / lan / ingress / tunnel / tailnet
    janitor/           interval-based TTL expiry
    webhook/           mutating admission webhook
    k8s/               typed k8s API clients (DI)
  manifests/           CRD + RBAC + Deployment + Webhook YAML
web/                   reserved (Vite + Chakra dashboard, v0.3+)
spike/                 original bash POC (kept for reference)
docs/                  AI-readable design + ops docs

MCP

bun run mcp (or installed bin heph-mcp) starts an MCP stdio server. Exposes one tool per CLI verb (heph_create, heph_up, heph_down, heph_touch, heph_url, heph_status, heph_logs, heph_patch, heph_ls, heph_show) plus heph://overlay/<name> resources for each overlay file.

To wire up Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "eph": {
      "command": "heph-mcp",
      "cwd": "/absolute/path/to/your/project-with-heph.yaml"
    }
  }
}

Then in Claude: "spin up an env for branch foo with postgres" → calls heph_create.

The server's cwd must contain the heph.yaml you want to operate on. To operate on multiple projects, register one mcpServers entry per project with distinct names (e.g. eph-myapp, eph-otherapp).

status

v0.1.0 surface complete. acceptance criteria all green:

• heph create deploys a working multi-service env
• URL reachable from outside (Cloudflare quick-tunnel)
• rm -rf source → teardown
• TTL expiry → janitor cleanup (verified at 8min wall clock for ttl=6m)
• N concurrent envs without collision

post-v0.1.0 deferrals are listed at the bottom of docs/08-next-steps.md.