# Heym

Self-hosted runtime for agentic workflows, driven by MCP, with its agent also served over A2A.

A Python and Vue platform for building and running workflows of agents and fixed steps, with a visual canvas, human review checkpoints, evals, traces and cost tracking. Workflows run from REST, schedules, triggers and MCP, and the Heym Agent behind the Chat tab can also be called over A2A. The core is free to self-host under MIT with the Commons Clause, which is source-available, not open source; Heym Work is a paid layer for business teams.

Alternative to: n8n, Zapier, Make

- Capabilities: adaptable, operable
- Vertical: agent-infrastructure
- Shape: product
- Form factor: web-app
- Execution model: hybrid
- Provenance: mixed (recorded, never ranked)
- Repo: https://github.com/heymrun/heym (MIT with Commons Clause), 1236 stars, last commit 2026-11-03
- Last activity: 2026-11-03
- Page: apps/heymrun--heym.html
- JSON: apps/heymrun--heym.json

## Use it when

- I want to build agent workflows on my own servers without paying per execution
- I want my coding agent to build, test and run workflows for me through one MCP tool
- I want a person to approve what an agent does before the run continues
- I want another agent to send tasks to my self-hosted workflow platform over A2A

## Gotchas

- The Commons Clause forbids selling a product or service whose value comes substantially from Heym, and it names hosting and consulting fees. An agency that charges to host or support Heym needs a commercial license
- A2A is off by default and rides on the Heym Agent: turn on the agent, pick a credential and model, then tick Enable A2A. Until then the card address returns 404
- A2A 1.0 only: 0.3 method names such as message/send are refused, push notifications are not offered, and file parts are refused
- Named servers serve their card at /api/a2a/servers/{server_id}/agent-card.json, not the well-known path
- heym_chat is one plain-language tool, so an MCP client's reach runs through a model on your own credential
- Test runs from heym_chat are real runs and their side effects happen
- An agent cannot enter a credential; a person has to save it on a Heym page

## Editions

- Heym Core: Free, closed source
  - source: https://github.com/heymrun/heym
  - container: docker pull ghcr.io/heymrun/heym:latest
- Heym Work: €99 per month, closed source
- Enterprise: Free, closed source

## Adaptable: make it yours

Effort: config-only (22 things to edit), surface kind admin-ui

ENVIRONMENT-VARIABLES.md lists every setting: database, keys, sandboxes, plugins and cluster roles. Most are deployment values. Business behavior lives in workflows, which are built on the canvas or by heym_chat, stored in the database, and moved as JSON. Custom nodes install as zip packages with a plugin.json when HEYM_PLUGINS_ENABLED is on, and agents take SKILL.md files. Changing the AI Assistant's own prompt means editing backend/app/services/workflow_dsl_prompt.py.

- Env vars: DATABASE_URL, ENCRYPTION_KEY, SECRET_KEY, ALLOW_REGISTER, FRONTEND_URL, CORS_ORIGINS, TIMEZONE, HEYM_PLUGINS_ENABLED, HEYM_PLUGIN_ADMIN_EMAILS, HEYM_PLUGINS_DIR, HEYM_PYTHON_TOOL_SANDBOX, HEYM_MCP_STDIO_SANDBOX, HEYM_MCP_ALLOW_PRIVATE_URLS, HEYM_HTTP_ALLOW_PRIVATE_URLS, HEYM_OTEL_ENABLED, HEYM_CLUSTER_ENABLED
- Config files: .env.example, ENVIRONMENT-VARIABLES.md, docker-compose.yml, docker-compose.cluster.yml, deploy/kubernetes
- Prompt files: backend/app/services/workflow_dsl_prompt.py
- Accounts you'll need: At least one model provider account, such as OpenAI or Google, or your own model endpoint

## Operable: what an agent can drive

Operability: official. Interface: mcp at https://heym.run/docs/tabs/mcp-tab (published by the builder, local).

### Reach (partial coverage)

- Build and revise workflows from plain language: reachable. heym_chat runs in build mode: it saves, test-runs and fixes a workflow, per frontend/src/docs/content/tabs/mcp-tab.md
- Run workflows: reachable. workflows with the MCP toggle on appear as tools; heym_execution_status follows queued runs
- Inspect analytics, run history and failures: reachable. heym_chat reports analytics, recent executions and live runs, per mcp-tab.md
- Review human-in-the-loop checkpoints: reachable. heym_chat can approve, edit or refuse pending reviews, per mcp-tab.md
- Manage Board cards: reachable. heym_chat lists boards, creates cards and reads card detail, per mcp-tab.md
- Manage data tables: reachable. heym_chat creates tables and columns and writes rows, per mcp-tab.md
- Build dashboards: reachable. heym_chat adds, renames and deletes widgets and tidies layouts, per mcp-tab.md
- Create and run evals: reachable. heym_chat creates, edits and runs prompt and agent eval suites, per mcp-tab.md
- Enter credentials: not reachable. mcp-tab.md: a person signs in and saves the value on a Heym page; the MCP client never receives it
- Turn on MCP and A2A, and set team access: not reachable. the toggles, keys and model choice are set in the MCP / A2A tab; heym_chat only reads teams

## A2A Protocol

Role: server (other agents can call it). Status: supported. Version: 1.0. Bindings: JSONRPC.
Agent Card: /.well-known/agent-card.json on each deployment. Source: https://heym.run/docs/reference/a2a (published by the builder). backend/app/api/a2a.py serves the Agent Card and POST /api/a2a, backend/app/services/a2a/agent_card.py declares JSONRPC at protocol version 1.0, and backend/tests/test_a2a_conformance.py checks the wire format against a2a-sdk; backend/app has no A2A client, and the public card at heym.run is a site-help agent, not this software.

Reach describes the stated interface, not A2A.

## Code stack

- Languages: Python, TypeScript, Vue
- Frameworks: FastAPI, Vue.js, SQLAlchemy
- Package manager: uv
- Database: PostgreSQL, Qdrant (optional)
- Hosting target: Docker, Docker Compose, Kubernetes

## Model stack

- Providers: OpenAI, Google, custom model endpoints through a Custom credential
- Models: none
- Keys you need (names only): ENCRYPTION_KEY, SECRET_KEY
- Prompts live in: prompts on LLM and Agent nodes, stored in each workflow, SKILL.md files attached to agents, backend/app/services/workflow_dsl_prompt.py
- Tools: heym_chat MCP tool, workflows published as MCP tools, MCP servers, Python tools and skills attached to Agent nodes

## Skills

contributor: One skill for writing Heym's docs. Skills an Adopter attaches to agents are created in the product.
- Paths: .cursor/skills/heym-documentation/SKILL.md

## Evidence and confidence

- formFactor: README.md: canvas and tabs in a Vue frontend over a FastAPI backend, opened at localhost:4017 (confidence 0.85)
- executionModel: the workflow graph runs as fixed orchestration, and LLM and Agent nodes call a model at runtime (confidence 0.85)
- operability: frontend/src/docs/content/tabs/mcp-tab.md: Heym serves {origin}/api/mcp/sse with an API key or OAuth; the REST execute endpoints are in reference/webhooks.md (confidence 0.9)
- effort: ENVIRONMENT-VARIABLES.md and .env.example are mostly deployment values; reference/plugin-authoring.md covers custom nodes; workflows are built in the app (confidence 0.7)
- editions: LICENSE, COMMONS-CLAUSE.md, reference/enterprise.md and heym.run/pricing: Core free, Heym Work EUR 99 per paid seat per month with a five-seat minimum, Enterprise custom (confidence 0.85)
- active: GitHub API pushed_at 2026-11-03 and release v0.0.145 on 2026-11-03
- provenance: two human contributors lead the history, and AGENTS.md plus a heym-coder contributor show agent-assisted development
- alternativeTo: frontend/src/docs/content/getting-started/why-heym.md compares Heym with n8n, Zapier and Make.com
- a2aRole: server only: reference/a2a.md describes inbound methods, and no A2A client import or call was found in backend/app
- reach:  (confidence 0.75)

## Open questions

- Reach and A2A were read from docs and source; Heym was not run, no MCP tool was called, and no deployment's Agent Card was fetched
- heym.run/.well-known/agent-card.json is live, but it describes the Heym Site Agent at heym.run/a2a, which searches the website. It was left out of a2a.agentCard because the page would show it in place of the per-deployment path; is that the right call?
- Reach for heym_chat comes from the Builder's list of abilities, and a model decides each step, so how reliably each job completes is unknown
- Which jobs the Chat engine can do for vector stores, Portal publishing and alert creation was not confirmed; the docs show it can read alerts

## Sources

- https://github.com/heymrun/heym (sourcing:agent-infrastructure:a2a-topic)
- https://heym.run/docs/reference/a2a (analysis:agent-infrastructure)
- https://heym.run/docs/tabs/mcp-tab (analysis:agent-infrastructure)
- https://heym.run/pricing (analysis:agent-infrastructure)
- https://heym.run/.well-known/agent-card.json (analysis:agent-infrastructure)