# Heym: self-hosted AI-native workflow automation on a visual canvas

> Heym is a Python and Vue platform that treats AI as the execution model rather than a bolt-on, with a drag-and-drop canvas, agent orchestration, MCP support and self-hosted deployment. It installs with a single shell script, and its licence is not plain MIT.

**heymrun/heym** — Build agentic systems. Run them with confidence. Orchestrate agents, automate business processes, inspect every execution, and keep humans in control. Deploy Heym on your own infrastructure.

- Repository: https://github.com/heymrun/heym
- Website: https://heym.run
- Stars: 1,305 · Forks: 96
- Language: Python
- License: NOASSERTION
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/heymrun-heym

## The problem Heym targets: automation platforms that add AI after the fact

Most workflow tools began as trigger-action engines. A form submission fires a webhook, the webhook calls an HTTP node, the HTTP node writes a row. AI arrived later as one more node type bolted onto that graph. Heym's README states the opposite design premise directly: "Unlike platforms that started as classic trigger-action automation and layered AI on later, in Heym AI is the execution model." That single sentence explains most of the product decisions that follow.

The audience is not the citizen automator connecting a spreadsheet to a chat app. It is a team that has to run multi-agent pipelines, keep a human in the approval loop, and answer questions about what an agent actually did during a run. The README lists run history, LLM traces, evals, logs, OpenTelemetry export and cost tracking in USD as first-class output of every execution. Those are the features that usually sit behind an enterprise plan, and Heym's stated position is that they ship in the free self-hostable build. The repository's topics include human-in-the-loop, evals, mcp-server and self-hosted, which matches that framing.

## How Heym executes a workflow: canvas, orchestrator, subagents, traces

The working unit is a graph drawn on a canvas. Nodes cover LLM calls, agents, vector stores, web scrapers, HTTP calls and message queues. The README describes four ways to produce that graph: the visual canvas, natural language, voice, templates, or Agent skills. The natural-language path is the one it demonstrates. A prompt such as "Create a workflow for me that includes a Roadmap Agent and a Best Food Agent. When the Orchestrator Agent receives a request, it will invoke these subagents in parallel and return the result to the user" is given as an example that produces the workflow on the canvas.

The execution pattern behind that example is an orchestrator with subagents. The README argues for it on concrete grounds: for a request with two unrelated parts, subagents can work in parallel, which "tends to finish faster, keeps each model turn focused (less context bloat), and avoids pressuring one model to produce two large, unrelated answers in a single reply." It also notes the alternatives work. Two separate LLM calls, or several calls in sequence merged in a final step, are valid patterns; the README just calls them usually slower for multi-part asks.

The same workflow can be invoked from five places according to the README: the canvas, REST execution endpoints, SSE streaming, MCP clients, or a public Portal chat UI. Observability is not a separate product. Run history, traces, evals, logs, OpenTelemetry export and USD cost tracking are attached to executions. The backend is Python with FastAPI, the frontend is Vue 3 with TypeScript and Bun, and the repository ships three compose files: docker-compose.yml, docker-compose.worker.yml and docker-compose.cluster.yml, which suggests a single-node default and a worker or clustered topology for larger deployments.

## Installing Heym locally and running a first workflow

The README's quick start is one line. Clone the repository, change into it, and run the shell script:

```bash
git clone https://github.com/heymrun/heym.git && cd heym && ./run.sh
```

That script is also what generates the required secrets. The .env.example file marks ENCRYPTION_KEY and SECRET_KEY as REQUIRED and notes they are auto-generated by run.sh or deploy.sh, or set manually. It gives the generation commands if you would rather control the values yourself:

```bash
python -c "import secrets; print(secrets.token_hex(32))"
python -c 'import secrets; print(secrets.token_urlsafe(32))'
```

The first produces the credential encryption key, the second the JWT signing key, which the file says must be a cryptographically random value of at least 32 characters. On the database side, .env.example defaults POSTGRES_PORT to 6543 and POSTGRES_DB to heym, with DATABASE_URL left blank so it can be assembled from the POSTGRES_* values. If you deploy with Docker, docker-compose.yml maps the container's 5432 to that same 6543 on the host.

A local run is not the only path. The repository includes deploy.sh, docker-compose.yml, docker-compose.worker.yml and docker-compose.cluster.yml, and the README says workflows deploy instantly via Docker. The backend listens on BACKEND_PORT, which .env.example sets to 10105. Two features are off by default and worth knowing before you plan around them: HEYM_PLUGINS_ENABLED is false, and HEYM_PLAYWRIGHT_CUSTOM_CODE_ENABLED is false.

## The PostgreSQL storage move and the guard that blocks startup

Heym changed where PostgreSQL keeps its data, and the compose file enforces the change loudly. The postgres service entrypoint checks for a PG_VERSION file at /legacy-pgdata, which is a read-only bind mount of ./data/postgres. If that file exists while the named volume is empty, the container prints a FATAL message and exits 1 rather than starting.

The stated reason is specific: bind mounts on macOS via virtiofs and on Windows via WSL2 "do not honour the fsync guarantees PostgreSQL requires and corrupt the cluster over time." The fix is a named volume, postgres-data, and the migration command the error message prints is:

```bash
./deploy.sh --migrate-pgdata
```

The guard is a good design choice. A silent start would initialise an empty database and, in the entrypoint's own words, lose your workflows. The cost is that anyone upgrading an older deployment sees a hard failure on first boot and has to run the migration before the stack comes up. The compose file also notes the read-only legacy mount is safe to drop once every deployment has moved off the bind mount, so this is migration scaffolding, not a permanent fixture. The same entrypoint tries to install postgresql-16-pgvector at startup and continues without it if the package is unavailable, which means vector search behaviour can differ between hosts depending on whether that install succeeds.

## Where Heym is the wrong tool, and what to use instead

The custom code paths are deliberately fenced off, and that matters for anyone planning to extend Heym. Plugins are disabled by default via HEYM_PLUGINS_ENABLED=false, and .env.example explains why: install and uninstall run server-side code, so the feature is restricted to the operator emails listed in HEYM_PLUGIN_ADMIN_EMAILS. The playwrightCode field is arbitrary Python and is off by default through HEYM_PLAYWRIGHT_CUSTOM_CODE_ENABLED=false. When enabled, it runs in a throwaway sibling container with no docker socket, no backend mounts and no backend secrets. The sandbox setting HEYM_PLAYWRIGHT_SANDBOX accepts auto, docker or subprocess, and the file is blunt that subprocess is in-process and "NOT a security boundary; trusted / local dev only." Step-based Playwright nodes are unaffected and always available.

If your team needs a stable, versioned API and long deprecation windows, this is not that project yet. The releases listed are v0.0.107 on 2026-09-08, v0.0.106 on 2026-09-05 and v0.0.105 on 2026-09-03. Three patch releases in five days is a fast cadence on a 0.0.x line, and it implies you should pin a version rather than track main. If you want a mature trigger-action engine with a large integration catalogue and you do not need agent orchestration or per-run traces, Heym's AI-first model is extra machinery you will not use. The README itself frames the contrast with n8n-style platforms, and the repository's n8n-alternative topic makes the positioning explicit.

## Licence and the cost of keeping Heym current

The licence field reports NOASSERTION, and the repository explains why. There is an MIT badge in the README, but there is also a Commons Clause badge, a COMMONS-CLAUSE.md file at the top level, and a LICENSE file. The README says the enterprise offering covers "commercial licensing, deployment help, dedicated support, and additional security layers." Read COMMONS-CLAUSE.md before you build a product on Heym; the combination of an MIT badge and a Commons Clause file is exactly the situation where the answer depends on your use, and this article does not give legal advice.

Upgrade cost is mostly operational. The database migration guard means a version bump can require running ./deploy.sh --migrate-pgdata before the stack starts, and the compose file treats the legacy mount as temporary. Secrets are another recurring item: ENCRYPTION_KEY and SECRET_KEY are required, and because run.sh and deploy.sh auto-generate them when they are blank, a redeploy from a fresh checkout can produce new values unless you set and persist them yourself. The repository ships a VERSION file and a set-version.sh script, so version state is tracked in the tree. The README does not document a rollback procedure, and the release notes for the three listed versions are not published in the repository tree. Budget for reading each release before you move a production instance.

## Conclusion

Heym fits teams that need to run agent workflows on their own infrastructure and want execution history, traces and MCP wiring as core features rather than paid tiers. Skip it if you need a stable API surface: the release history shows v0.0.107 on 2026-09-08 and the project has not reached 1.0. Before adopting, read COMMONS-CLAUSE.md and confirm what your use counts as, then run ./run.sh locally and check that the generated ENCRYPTION_KEY and SECRET_KEY are stored somewhere you control.

## FAQ

### How do I install and run Heym locally?

The README gives a single command: clone the repository, change into it, and run ./run.sh. That script also auto-generates the required ENCRYPTION_KEY and SECRET_KEY values unless you set them yourself in the environment file.

### Does Heym need Docker, and which compose files does it ship?

The README says workflows deploy instantly via Docker, and the repository includes docker-compose.yml, docker-compose.worker.yml and docker-compose.cluster.yml, plus a deploy.sh script. The default compose file runs PostgreSQL 16 with a named volume for its data.

### What licence does Heym use?

The repository reports NOASSERTION. It carries an MIT badge in the README but also a Commons Clause badge and a COMMONS-CLAUSE.md file at the top level, and the README describes commercial licensing as part of the enterprise offering.

### Can Heym run multi-agent workflows in parallel?

Yes. The README describes an orchestrator pattern where subagents handle separate parts of a request in parallel, and gives the example of a Roadmap Agent and a Best Food Agent invoked together by an Orchestrator Agent. It notes sequential calls and a final merge step also work but are usually slower for multi-part asks.

## Sources

- [heymrun/heym on GitHub](https://github.com/heymrun/heym)
- [Issues](https://github.com/heymrun/heym/issues)
- [Project website](https://heym.run)
- [README](https://github.com/heymrun/heym/blob/main/README.md)
- [Releases](https://github.com/heymrun/heym/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/heymrun-heym