<div align="center"> <br/> <img src="./docs/readme-assets/logo.svg" width="80" height="80" alt="Heym Logo"/>

Heym

Build agentic systems. Run them with confidence.

<p align="center"> Heym is a self-hosted runtime and platform for building, orchestrating, running, observing, evaluating, and controlling agentic systems on your infrastructure. </p> <p align="center"> Visually compose agents and deterministic workflows, or generate them with AI. Connect models, tools, MCP, company knowledge, and internal systems, then operate them with approval checkpoints, retries, and visibility into execution and model costs. </p> <p align="center"> <a href="https://heym.run">heym.run</a> </p> <p align="center"> <strong>Try locally:</strong> <code>git clone https://github.com/heymrun/heym.git && cd heym && ./run.sh</code><br/> <a href="#-quick-start">Quick Start</a> · <a href="#deploy--call-workflows">Deploy & Call Workflows</a> · <a href="#extending-heym">Extending Heym</a> · <a href="SECURITY.md">Security</a> </p> <br/>

<br/> <img src="./docs/readme-assets/hero.svg" width="100%" alt="Heym self-hosted agentic runtime animation"/> <br/> </div>

---

What Is Heym?

In Heym, a workflow defines how agents, deterministic steps, tools, and data work together. The runtime executes that graph, coordinates dependent and parallel work, records execution history, and supports human review checkpoints.

The canvas is one interface into Heym. It is not Heym itself. Use it to build, inspect, debug, and understand systems running on the runtime. Those same workflows also run through APIs, schedules, event triggers, MCP clients, and Portal conversations.

Explore the product site at heym.run.

One Runtime for the Agent Lifecycle

Build → Orchestrate → Run → Observe → Evaluate → Control → Expose

These are connected parts of operating an agentic system in Heym.

| Stage | What you do in Heym | |-------|---------------------| | Build | Compose agents and deterministic workflows visually, generate them with AI, or start from reusable templates and skills. | | Orchestrate | Coordinate agents, sub-agents, sub-workflows, and tools with explicit data flow, branching, and parallel execution where dependencies allow. | | Run | Execute from APIs, schedules, event triggers, or interactive interfaces, with configurable retries, error paths, and browser automation. | | Observe | Inspect execution history, live state, traces, tool calls, tokens, latency, errors, and model costs. Review analytics and alerts, and export OpenTelemetry traces. | | Evaluate | Test prompts and model responses against expected outputs, compare results across models, and inspect saved evaluation runs. | | Control | Pause Agent execution at review checkpoints and resume from saved state after a human decision. Configure guardrails, credentials, authentication, and team access. | | Expose | Serve workflows through REST, SSE streaming, MCP tools, and Portal chat interfaces, or connect their results to in-app dashboard widgets. |

Use observations and evaluation results to refine prompts, tools, and workflow logic, then run and inspect the next iteration.

🗺️ Platform Overview

The workflow definition connects the build experience to execution. The runtime uses that definition to coordinate nodes and tools, while execution state feeds the interfaces people use to inspect, review, and consume the results.

| Part of the system | How it fits | |--------------------|-------------| | Build and inspect | The canvas, AI Assistant, templates, and Expression DSL create and edit workflow definitions. The same canvas can attach to an active execution for inspection. | | Orchestrate and execute | The executor coordinates agents, deterministic nodes, sub-workflows, parallel branches, retries, and review checkpoints. | | Connect tools and data | Nodes and agent tools reach models, HTTP APIs, MCP servers, internal knowledge, persistent memory, databases, queues, and files. | | Operate and improve | History, traces, costs, analytics, alerts, logs, and OpenTelemetry reveal runtime behavior. Evals support prompt and model iteration; access controls and human review shape how systems run. | | Serve people and applications | REST and SSE endpoints, MCP tools, Portal conversations, Board jobs, and workflow-backed dashboards provide ways to invoke systems and use their results. |

<div align="center">

</div>

---

✨ Key Capabilities

Build: Agents, Workflows, and Connected Tools

• Visual and AI-assisted authoring. Build and inspect workflow graphs on the canvas, generate or revise them through the AI Assistant using text or voice, and reuse templates.
• Agents and deterministic logic. Combine LLM and Agent nodes with conditions, switches, loops, merges, data transformations, and sub-workflow calls. Use expressions in supported node fields.
• Multi-agent orchestration. Give an orchestrator named sub-agents and sub-workflows to call. Independent sub-agent calls can execute concurrently.
• Knowledge and persistent memory. Retrieve documents through RAG using Qdrant or PostgreSQL with pgvector. Enable per-agent knowledge graphs to retain facts across runs, with configurable sharing between agents.
• Tools and integrations. Connect communication services, developer tools, productivity apps, databases, queues, and storage through built-in nodes, HTTP APIs, and MCP. Use MCP Call nodes for deterministic tool invocation.
• Skills and custom behavior. Attach reusable SKILL.md instructions and optional Python tools to agents, create or revise skills with AI, install plugins, or implement custom nodes with typed configuration and execution handlers.

Run: Execute and Coordinate Work

• Parallel execution and recovery. Run independent nodes concurrently, synchronize branches with Merge, and configure retries, backoff, error paths, and model fallback.
• Schedules and triggers. Start workflows through cron, webhooks, messaging integrations, inbox events, WebSocket messages, and Heym platform events.
• Browser and coding agents. Automate browser tasks with Playwright and AI-assisted selector recovery. Run Codex or OpenCode Go against a repository as workflow steps, with diff and pull-request outputs.
• Agentic Kanban Board. Cards are persistent agentic jobs. Moving a card into a column runs its ordered workflow chain with card content, comments, history, and previous outputs, then writes results back to the card.
• Load distribution. Share eligible background runs across Heym instances through PostgreSQL, with execution weights configured in Settings → Instances.

Observe: Understand Execution and Cost

• History and live execution. Open a production run from History or a Board card, inspect its saved state, and follow live node progress, Debug logs, and final output.
• Traces and model costs. Inspect model requests, responses, tool calls, input/output tokens, latency, and errors. Calculate USD costs with maintained model pricing and custom overrides, and explore historical spending by model and time range.
• Analytics, logs, and alerts. Track execution volume, success rates, and duration; review logs; set alerts for errors, duration, token or USD spend, and run count. Export workflow, node, and Agent tool spans through OpenTelemetry.

Evaluate & Control: Improve Behavior and Keep Humans Involved

• Evals and analysis. Run repeatable prompt evaluations across models, compare expected and actual outputs, and review historical results. The Workflow Analyzer uses execution context to create a shared, editable Markdown report on purpose, step behavior, and improvement areas.
• Human review. Agent checkpoints pause execution for acceptance, edits, or refusal, then continue from a saved execution snapshot. A review branch can notify people through existing integrations.
• Security and access. Configure input guardrails, encrypted credentials, team sharing, execution tokens, and workflow authentication. Sign in with JWT authentication or OIDC SSO through providers such as Keycloak, Okta, Entra ID, Auth0, and Google.

Expose: Put Systems to Work

• REST, SSE, and MCP. Invoke workflows from applications, stream execution events, or publish workflows as tools for MCP clients.
• Portal and Chat. Publish workflow-backed chat interfaces with streaming, uploads, and conversation history. Use the Chat tab to call workflows and work with models and platform data.
• Dashboards, data, and files. Build custom dashboard widgets backed by workflows, manage structured Data Tables, and keep generated files in Heym Drive with team sharing and share links.

<div align="center"> <img src="./docs/readme-assets/key-capabilities.svg" width="100%" alt="Animated Heym runtime capabilities grid"/> </div>

---

🎬 Product Tour

One e-commerce sales campaign, followed end to end: workflow generation with the AI Assistant, human review, board execution, structured data, dashboards, traces, RAG, MCP, analytics, and team collaboration.

<div align="center"> <a href="https://www.youtube.com/watch?v=CWUy2zynCqc"> <img src="https://img.youtube.com/vi/CWUy2zynCqc/maxresdefault.jpg" width="100%" alt="Watch the Heym product tour on YouTube"/> </a> </div>

Product Demos

The demos follow an orchestrator and sub-agent system from creation to a chat interface. For a request such as “How do I get from Berlin to Frankfurt?” and “What should I eat there?”, the orchestrator can call independent sub-agents in the same turn, run those tasks concurrently, and combine their results.

Generate Workflows from Natural Language

Describe the agents, orchestration pattern, and user-facing result you want; Heym builds the workflow on the canvas.

![Workflow