Hearth

Modern teams are shipping more than stateless microservices. They are running event-driven jobs, durable workflows, tool-calling systems, and AI agents that can impact real business systems. Kubernetes gives excellent primitives, but turning those primitives into safe, auditable, outcome-focused platforms still takes too much glue code, too many YAML objects, and too many manual guardrails. Hearth exists to close that gap: it lets teams move faster from idea to production with stronger defaults, clearer policy boundaries, and built-in workflow/agent orchestration so platform effort goes into product outcomes, not integration overhead. It also treats runtime choice as a first-class platform decision, so containers are not your only option: workloads can run on container, WASM, or microVM backends based on intent and policy.

Hearth is a Kubernetes-native platform that lets you declare intent (what you want) instead of manually wiring many low-level Kubernetes objects (how to do it).

You use Hearth Custom Resources (CRDs) like Execution, Flow, Tool, and PolicySet. Hearth controllers then create and manage the underlying Kubernetes resources for you.

Who this is for

This guide is written for people who are new to Hearth and may be new to advanced Kubernetes platform concepts.

If you can run kubectl apply -f ..., you can use Hearth.

What Hearth does

Hearth gives you higher-level building blocks for modern workloads:

• Execution: run a service, job, function, or agent
• Flow: orchestrate multi-step work with retries and approvals
• Tool: register external/internal tools with policy and auditing
• PolicySet: enforce security defaults and access constraints
• RuntimeProfile: provision runtime classes and runtime readiness checks
• NodeRuntime: automate node runtime installation/verification (WASM, microVM)
• Gateway: define traffic ownership/exposure (optional)
• AgentSession: durable, policy-governed AI agent session
• ApprovalRequest: human-in-the-loop approvals
• TaskGraph / TaskGraphRun / FlowRun: execution graph and run tracking
• ToolCallAudit: immutable audit records for tool use

Why use Hearth instead of plain Kubernetes

Plain Kubernetes is powerful but low-level. For one business workflow, you often need many objects and integrations (Deployment, HPA, Service, ingress/gateway config, network policy, RBAC, workflow engine, approval mechanism, auditing).

Hearth gives you:

• Fewer YAML files to express the same outcome
• Secure defaults (identity, policy checks, approvals)
• Built-in workflow and agent primitives
• Built-in tool integration and audit trails
• Pluggable runtime and backend components

You still run on Kubernetes, but with an intent-first API.

Architecture at a glance

• Hearth runs as controllers + webhooks in hearth-system
• You apply Hearth CRDs in your app namespaces
• Controllers reconcile your intent into underlying resources
• Flow/tool gateways expose trigger and approval APIs

Prerequisites

For local testing:

• kubectl
• docker
• kind
• go (if building locally)
• make
• curl

Quick start (fastest path)

Run the full local end-to-end environment (cluster + install + smoke test):

make kind-e2e

What this does:

1. Creates (or reuses) kind cluster hearth-e2e
2. Installs cert-manager
3. Builds Hearth images locally
4. Loads images into kind
5. Installs Hearth with kind overlay
6. Runs smoke test end-to-end

At the end you should see:

• [smoke] success
• [kind-e2e] complete

Install Hearth on an existing cluster

kubectl apply -k config/default

This installs:

• CRDs
• RBAC
• controller manager
• tool gateway
• flow gateway
• mutating/validating webhooks
• cert-manager issuer/certificate resources

Core concepts in plain words

1) PolicySet

Your security and governance rules. Think of it as "default guardrails" for workloads and tools.

Example responsibilities:

• Require workload identity
• Deny privileged workloads
• Default-deny egress
• Require approval for certain high-risk tools

2) Execution

A single workload intent. You say what it is (Service, Job, Function, Agent) and runtime (container, wasm, microvm, or auto).

Hearth reconciles it into underlying resources.

3) Tool

A tool endpoint with schema/risk/policy metadata. Flows and agents can invoke it under policy control, and calls are audited.

4) Flow

A durable multi-step workflow. Steps can call executions/tools, pause for approval, and track run state.

5) AgentSession

A durable AI agent session tied to an Execution and constrained by PolicySet and tool permissions.

Typical first-time workflow

1. Create a namespace.
2. Apply a PolicySet.
3. Apply an Execution.
4. Apply one or more Tool objects.
5. Apply a Flow or AgentSession.
6. Trigger flow and handle approvals (if required).
7. Inspect FlowRun, TaskGraphRun, and ToolCallAudit.

Runtime note:

• For wasm and microvm executions, Hearth auto-creates default RuntimeProfile objects (wasm, microvm) if they do not exist.
• Use NodeRuntime when you want Hearth to automate node-level runtime bootstrap (installer DaemonSet + RuntimeClass + optional probe job).
• make kind-e2e also provisions these runtime profiles automatically.

End-to-end smoke test

If Hearth is already installed in your cluster:

make smoke-e2e

Useful options:

NS=hearth-smoke CLEANUP=1 make smoke-e2e
FLOW_GATEWAY_NS=hearth-system FLOW_GATEWAY_SVC=hearth-flow-gateway make smoke-e2e
KUBECONFIG_CTX=kind-hearth-e2e NS=hearth-smoke CLEANUP=1 make smoke-e2e

Smoke test validates:

• policy creation
• execution readiness
• flow compilation/triggering
• approval workflow
• flow completion
• agent session run linkage
• tool audit creation

Spec conformance run

Run the conformance runner (CRDs, runtime profiles, approval queue API, smoke path):

make spec-conformance

API endpoints you will use

On hearth-flow-gateway:

• Trigger webhook flow:

POST /trigger/webhook/{namespace}/{flowName}

• Trigger by event type:

POST /trigger/event/{namespace}/{eventType}

• List pending approvals:

GET /approvals?namespace={namespace}

• Approval queue (filter/sort/paginate):

GET /approvals/queue?namespace={namespace}&state=pending&tool={tool}&runRef={runRef}&sort=created_desc&limit=50&offset=0

• Approve:

POST /approvals/{namespace}/{approvalName}/approve

• Reject:

POST /approvals/{namespace}/{approvalName}/reject

Example manifests

The repository includes ready-to-apply examples in:

• config/samples/hearth_v1alpha1_policyset.yaml
• config/samples/hearth_v1alpha1_runtimeprofile_wasm.yaml
• config/samples/hearth_v1alpha1_runtimeprofile_microvm.yaml
• config/samples/hearth_v1alpha1_noderuntime_wasm.yaml
• config/samples/hearth_v1alpha1_noderuntime_microvm.yaml
• config/samples/hearth_v1alpha1_execution.yaml
• config/samples/hearth_v1alpha1_tool.yaml
• config/samples/hearth_v1alpha1_flow.yaml
• config/samples/hearth_v1alpha1_agentsession.yaml
• config/samples/hearth_v1alpha1_gateway.yaml
• config/samples/hearth_v1alpha1_taskgraph.yaml

Apply sample resources:

kubectl apply -f config/samples/

Observability and status checks

Check core objects:

kubectl get executions,flows,flowruns,taskgraphruns,tools,toolcallaudits,approvalrequests

Inspect one object deeply:

kubectl describe flowrun <name>
kubectl get flowrun <name> -o yaml

Controller logs:

kubectl -n hearth-system logs deploy/hearth-controller-manager
kubectl -n hearth-system logs deploy/hearth-flow-gateway
kubectl -n hearth-system logs deploy/hearth-tool-gateway

Build and development commands

make fmt vet test
make build build-gateway build-flow-gateway

Generate CRDs/manifests:

make generate manifests

Run controller locally:

make run

Helm

helm lint charts/hearth
helm install hearth charts/hearth

Pluggable modules (for advanced users)

Hearth is modular. Key extension points:

• Runtime adapters: internal/runtimeadapter
• Source resolvers (image/wasm/git/artifact): internal/source
• Tool-plane policy parts (quota/approval/audit/schema): internal/toolplane
• Workflow backend modes (local, argo): controllers/taskgraphrun_controller.go

Troubleshooting

Webhooks rejecting resources

• Ensure PolicySet referenced by policyRef exists in the same namespace.
• Check webhook/controller logs in hearth-system.

Flow is stuck in Paused

• List approvals and approve pending requests.

kubectl get approvalrequests -n <namespace>

Smoke test fails

• Verify gateway service exists:

kubectl -n hearth-system get svc hearth-flow-gateway

• Re-run with explicit context:

KUBECONFIG_CTX=kind-hearth-e2e CLEANUP=1 make smoke-e2e

Additional docs

• User guide: docs/user-guide.md
• Runtime integration: docs/runtime-integration.md
• WASM setup guide: docs/wasm-setup-guide.md
• microVM setup guide: docs/microvm-setup-guide.md
• Kind e2e spec: docs/specs/kind-e2e-spec.md
• Feature completeness matrix: docs/specs/feature-completeness.md
• Multi-tenancy/security notes: docs/security/multi-tenancy.md