heymrun/heym

Heym

Build agentic systems. Run them with confidence.

Heym is a self-hosted runtime and platform for building, orchestrating, running, observing, evaluating, and controlling agentic systems on your infrastructure.

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.

heym.run

Try locally: git clone https://github.com/heymrun/heym.git && cd heym && ./run.sh
Quick Start · Deploy & Call Workflows · Extending Heym · Security

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.

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

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

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

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.

• 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.

• 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.

• 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.

• 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.

• 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.

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.

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.

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

Example prompt

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.

Start a runtime execution from the canvas and inspect each step as results move through the graph. APIs, schedules, triggers, and MCP can invoke the same workflow.

Create agent skills from natural language, preview the generated SKILL.md, and attach them to the agent.

Example prompt

Create a skill for me and add it to the agent. The Orchestrator Agent will call this skill after receiving information from the subagents, and the skill will create a simple execution plan explaining what can actually be done in the destination city.

Turn a workflow into a chat experience so users can invoke the orchestration with a natural request.

Example prompt

I live in Berlin and am planning to go to Frankfurt. How many kilometers is it on the Autobahn? Also, where can I find the best doner in Frankfurt?

Visual Canvas: Multi-agent orchestration, RAG and MCP nodes, human-in-the-loop checkpoints	MCP Server: Publish workflows as tools for Claude, ChatGPT, or Cursor
Traces: Inspect model requests, responses, tokens, latency, and cost	Analytics: Execution volume, success rate, latency, and time saved per workflow

Prefer to watch it first? Set Up Heym Locally in Under 2 Minutes walks the whole path: clone the repository, start PostgreSQL and create your account on a local instance.

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

# OR: with .env file (run.sh auto-generates SECRET_KEY and ENCRYPTION_KEY)
git clone https://github.com/heymrun/heym.git
cd heym
cp .env.example .env
./run.sh

Open http://localhost:4017 to create your account and start building. run.sh starts PostgreSQL, the backend, and the frontend, and generates SECRET_KEY and ENCRYPTION_KEY when needed.

Prerequisites: Bun, Python 3.11+, UV, and Docker. For containers, use the deployment options below. See ENVIRONMENT-VARIABLES.md for every setting and its default.

Heym runs on your infrastructure with PostgreSQL as its core database. The standard Compose setup includes PostgreSQL, the backend, and the frontend, with local volumes for persistent files. RabbitMQ and Redis are integrations you connect when a workflow needs them. RAG can use the built-in PostgreSQL/pgvector backend or an external Qdrant server; S3 is available through its integration node.

Use Docker Compose and Python 3 for production deployment:

cp .env.example .env
./deploy.sh              # Build and deploy (auto-generates keys if empty)
./deploy.sh --down       # Stop services
./deploy.sh --logs       # View logs
./deploy.sh --restart    # Restart services

Register your admin account first, then set ALLOW_REGISTER=false in .env and restart to close registration in production.

The release image bundles the frontend and backend. The examples below connect it to an existing PostgreSQL database on the host; set DATABASE_URL to your database address and credentials. On Linux, add --add-host=host.docker.internal:host-gateway when using that hostname.

# Docker with .env file
git clone https://github.com/heymrun/heym.git
cd heym
cp .env.example .env
# Generate required keys and write them into the placeholder lines copied from
# .env.example (replace in place: appending with >> would create duplicate entries):
SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
ENCRYPTION_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))")
sed -i.bak "s|^SECRET_KEY=.*|SECRET_KEY=${SECRET_KEY}|; s|^ENCRYPTION_KEY=.*|ENCRYPTION_KEY=${ENCRYPTION_KEY}|" .env && rm -f .env.bak
docker run --env-file .env \
  -e DATABASE_URL=postgresql+asyncpg://postgres:postgres@host.docker.internal:6543/heym \
  -p 4017:4017 \
  --shm-size 2g \
  -e FILE_STORAGE_DIR=/app/data/files \
  -e HEYM_PLUGINS_DIR=/app/data/plugins \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd)/data/files:/app/data/files" \
  -v "$(pwd)/data/plugins:/app/data/plugins" \
  -v heym-codex-workspaces:/app/data/codex-workspaces \
  -v heym-opencode-workspaces:/app/data/opencode-workspaces \
  ghcr.io/heymrun/heym:latest

# OR: minimal, no .env file
docker run \
  -e ENCRYPTION_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))") \
  -e SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))") \
  -e DATABASE_URL=postgresql+asyncpg://postgres:postgres@host.docker.internal:6543/heym \
  -e FILE_STORAGE_DIR=/app/data/files \
  -e HEYM_PLUGINS_DIR=/app/data/plugins \
  -p 4017:4017 \
  --shm-size 2g \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd)/data/files:/app/data/files" \
  -v "$(pwd)/data/plugins:/app/data/plugins" \
  -v heym-codex-workspaces:/app/data/codex-workspaces \
  -v heym-opencode-workspaces:/app/data/opencode-workspaces \
  ghcr.io/heymrun/heym:latest

The mounts and runtime settings support these capabilities:

• Playwright: --shm-size 2g gives Chromium room for browser tasks. Step-based Playwright runs inside the Heym container; custom playwrightCode uses a sibling container with its own shared-memory setting. Compose configures this for you.
• Heym Drive: FILE_STORAGE_DIR=/app/data/files points file storage at the mounted directory, keeping uploads and generated files across container restarts.
• Plugins: HEYM_PLUGINS_DIR=/app/data/plugins and its mount preserve installed plugin packages.
• Skills and Codex: the heym-codex-workspaces volume connects the runtime to its hardened sibling containers. Per-run isolation uses Docker Engine 25.0+.
• OpenCode Go: the heym-opencode-workspaces volume preserves the workspace shared with its sibling runner.
• Docker access: the socket supports sandbox containers and MCP stdio execution. It grants broad host control, so restrict access to your deployment. Docker log access is configured separately with DOCKER_LOGS_ENABLED and DOCKER_LOGS_ALLOWED_EMAILS; create allow-listed accounts before opening registration.

Connect additional Heym instances to the same PostgreSQL database to distribute eligible background workflow runs. Configure their shares from Settings → Instances. PostgreSQL carries the queue and coordination, so the cluster needs no separate message broker or direct instance-to-instance connection.

The main instance serves the UI, API, MCP, and Portal and owns local files and installed plugins. Workers execute eligible queued runs; workflows that depend on main's local storage or workspaces run there. The Load Distribution guide covers placement, shared keys, database sizing, ingress, and upgrades, with cluster and worker Compose examples.

Heym is in its pre-1.0 release series. Follow the version badge and releases for updates. The deployment guide and security policy provide the operational setup reference.

Connect Heym to the systems your team already uses. Choose built-in integrations, HTTP APIs, MCP, reusable skills, plugins, or custom nodes to bring tools and data into the runtime.

The node library brings agents together with deterministic logic, triggers, data, and outputs:

Heym Drive stores uploaded and generated files with public or password-protected share links, team sharing, and bulk ZIP, share, and delete actions. See Drive.

See the node reference and integration guides for operations, credentials, and setup.

As a client: Agent nodes discover and call tools from configured MCP servers over SSE, Streamable HTTP, or stdio. The MCP Call node invokes a selected tool directly when the workflow defines the call.

As a server: Publish Heym workflows as tools at /api/mcp/sse for Claude Desktop, Cursor, and other MCP clients. See MCP configuration.

Skills are portable capability bundles: a SKILL.md instruction file plus optional Python tools and assets. Drop a .zip or .md onto an Agent node, or use AI Build to draft and iterate on skills from chat. Reuse and share them across workflows and teams.

Describe the system you want in plain text or voice. The assistant generates nodes and edges directly in the editor, where you can inspect and refine the resulting workflow.

When a workflow already contains Agent skills, the assistant sends only each skill's SKILL.md into the builder context. Large .py files and binary attachments stay out of the prompt so workflow editing remains reliable even with complex skills loaded on the canvas.

Inside the Agent node's Skills section, use AI Build to create a new skill or the inline sparkle action to revise an existing one. The modal streams a chat conversation, previews generated SKILL.md and .py files live, and saves them back through the same ZIP ingestion path used by manual skill uploads.

Build orchestrator/sub-agent pipelines visually. One agent delegates tasks to named sub-agents or sub-workflows, composing their results into a shared response. Configure reasoning effort and temperature per agent.

Upload PDFs, Markdown, CSV, or JSON to a managed vector store backed by Qdrant or PostgreSQL/pgvector. Wire a RAG node into a workflow for semantic search, with retrieved context flowing into an LLM or Agent node.

Input → RAG (search) → LLM (answer with context) → Output

Enable a knowledge graph for an Agent node to retain entities and relationships across runs. Heym adds graph context to the agent's prompt and merges new facts in the background after successful runs. Use the graph editor to inspect and edit memory or grant other agents read or read/write access. See Agent Persistent Memory.

Configure reasoning effort, temperature, and fallback models for Agent execution. LLM nodes support text, vision, structured output, and provider-native Batch API mode for supported endpoints, with live status branches and per-item results. Agent message history is automatically compressed as it approaches the model context limit, with compression events visible in Debug logs, History, and Traces. See the LLM node and Agent node references.

Independent nodes run concurrently based on graph dependencies. Use the Merge node to synchronize parallel branches and combine their results. The graph defines the execution order. See Parallel Execution.

Playwright nodes support visual steps, AI-generated actions, and full-code browser automation. Enable Auto Heal to use page context for selector recovery when an action fails. See the Playwright node reference for configuration.

Configure retry on failure and error branching on nodes:

Input ──→ HTTP ──→ Output
               └─── error ──→ Error Handler

• Retry: automatically re-run a failed node with configurable attempts and backoff
• Error branch: route failures to a dedicated path instead of stopping the workflow
• Error context: access $nodeName.error in downstream nodes

Inspect saved inputs, outputs, node results, errors, timing, and execution logs. History connects a run to its trigger and, in a cluster, the instance that executed it.

Open a Running entry from either History dialog or the run list inside a Board card, and Heym attaches the editor to that exact execution over SSE. This works for runs started by webhooks, schedules, chat, MCP, integrations, or the Agentic Kanban Board. Completed nodes are restored immediately; the current and pending nodes keep pulsing; Debug logs and the final output arrive incrementally. Leaving the editor disconnects only the observer and never cancels the production run.

Inspect model requests and responses, tool-call details, per-call timing, token usage, errors, and skills passed to the model. Use traces alongside workflow history to follow the relationship between model behavior and the surrounding execution. See Traces.

Heym records input and output tokens and calculates USD costs from maintained model pricing data. Inspect costs per trace and explore historical usage and spending by model and time range. Add custom model pricing overrides for your own endpoints or rates.

Cost visibility also connects to operations: alerts can evaluate token or USD spend over a chosen time window. See Traces and cost analytics for pricing and usage views.

Review execution volume, success rates, latency, and estimated time saved by workflow in Analytics. Follow incremental Debug logs while inspecting a run, and enable access-controlled Docker log viewing and streaming through the Logs tab.

Set thresholds over a time window on four metrics: error count, run duration (max, average, or p95), LLM token or USD spend, and execution count. Scope an alert to one workflow or all workflows you can access.

A five-step wizard covers type, scope, condition, response, and review. Describe the rule in natural language to fill the form with AI, then preview the condition against historical windows before saving. By default, an alert fires once and waits for the metric to recover before firing again.

An alert can run a workflow with the observed value, threshold, window, and contributing detail as input. Use existing Slack, email, or Telegram nodes to deliver notifications. The Chat tab can explain which alerts exist and why one triggered. See Alerts.

Create suites with a system prompt, test inputs, and expected outputs. Run the same cases across multiple models and repeat runs to compare responses. Inspect scores, actual versus expected output, latency, token usage, and saved run history.

Use evaluation results to guide prompt changes, generate additional test data, or request an AI-assisted prompt revision. Pair those results with execution traces and Workflow Analyzer reports to improve the system you operate. See Evals and Workflow Analysis.

Agent review checkpoints turn human approval into part of execution. When an agent requests review, Heym saves an execution snapshot and marks the run as pending. The agent's review branch can send the review link and summary to Slack, email, or another notification flow.

A reviewer can Accept, Edit & Continue, or Refuse. Heym resumes from the saved snapshot with the decision and reviewed text available to downstream nodes. An agent can request further checkpoints during the same run. See Human-in-the-Loop.

Configure category-based and multilingual guardrails on LLM and Agent input messages. Checks run before the model call and route violations through the workflow's error-handling paths.

Manage encrypted credentials and team sharing, use scoped execution tokens, configure workflow authentication and rate limits, and connect an OIDC identity provider for SSO. See Guardrails, Teams, Credentials Sharing, SSO, and Security.

Export a root span per workflow run, a child span per node, and Agent tool spans (heym.agent.tool.execute) over OTLP/HTTP to Jaeger, Grafana Tempo, Honeycomb, Datadog, or any OpenTelemetry backend. Spans carry workflow id, node type, status, duration, LLM token usage, and tool identity/status, with W3C trace context propagated across inbound webhooks, outbound HTTP, and sub-workflows. Enable tracing with the HEYM_OTEL_* environment variables and review status under Settings → Observability. See OpenTelemetry Tracing for configuration and span details.

The same runtime can serve people, backend services, and external agents. Choose an interface for how the system will be used:

The editor's Run with cURL dialog generates commands for REST or SSE, including per-node start messages and live event output. See Webhooks and SSE Streaming for authentication, request bodies, and event formats.

Turn a workflow into a public chat interface at /chat/{slug} with optional per-user authentication, streaming responses, file uploads, and multi-turn conversation history. Build internal tools and customer-facing chat interfaces directly from your workflow. See Portal.

Each custom dashboard widget is backed by its own hidden Heym workflow. Fetch, transform, retrieve, or generate data through workflow logic and display the result as a chart in the dashboard. See Dashboard.

Reference and transform data between nodes with a clean syntax:

$input.text                         // Trigger input
$nodeName.field                     // Any upstream node output
$global.variableName                // Persistent global variable
$now.format("YYYY-MM-DD HH:mm")    // Date/time formatting
$UUID                               // Random unique ID
$range(1, 10)                       // Generate number range
$input.items.filter("item.active")  // Array filtering
$input.users.map("item.email")      // Array mapping
$input.text.upper()                // String helpers

Use expressions in supported node fields, including prompts, HTTP headers, conditions, email bodies, and Redis keys. See the Expression DSL reference.

heym/
├── frontend/src/
│   ├── components/     # Canvas, Nodes, Panels, Credentials, Evals, MCP, Teams
│   ├── views/          # DashboardView, EditorView, ChatPortalView
│   ├── stores/         # Pinia (workflow, auth, folder)
│   ├── services/       # API clients
│   └── docs/content/   # In-app documentation (Markdown)
├── backend/
│   ├── app/
│   │   ├── api/        # Routes: workflows, auth, mcp, portal, evals, traces
│   │   ├── models/     # Pydantic schemas
│   │   ├── services/   # Executor, node handlers, LLM, RAG, agent engine
│   │   └── db/         # SQLAlchemy models and database configuration
│   ├── tests/          # Backend unit tests
│   └── alembic/        # Database migrations
├── docker-compose.yml
├── run.sh              # Local development launcher
├── check.sh            # Project validation script
└── deploy.sh           # Docker production deployer

See ENVIRONMENT-VARIABLES.md for the complete reference.

Prerequisites: Bun ≥ 1.0 · Python ≥ 3.11 · UV · Docker

# Start all services (recommended)
./run.sh
./run.sh --no-debug    # INFO logging instead of DEBUG

Or start each service manually:

# Start database only
docker-compose up -d postgres

# Backend
cd backend && uv sync && uv run alembic upgrade head
uv run uvicorn app.main:app --reload --port 10105

# Frontend (separate terminal)
cd frontend && bun install && bun run dev

Validation:

./check.sh    # Frontend lint/typecheck; backend format, lint, and tests
# If SECRET_KEY is not exported locally:
SECRET_KEY=test-secret-key-for-tests-only-32-bytes ./check.sh

# Frontend unit and browser tests run separately
(cd frontend && bun run test)
./run_e2e.sh

Or run individually:

(cd frontend && bun run lint && bun run typecheck && bun run test)
(cd backend && uv run ruff check . && uv run ruff format .)

Every pull request runs the PR checks workflow: a file line-limit check, frontend ESLint, TypeScript strict typecheck, frontend Vitest unit tests, production build, backend Ruff format and lint, the backend unit test suite, and Playwright E2E tests against a live Postgres service.

The backend publishes its OpenAPI reference at /docs on the backend server (port 10105 in local development).

For a complete list of all features with short descriptions, see Full Feature Set. It covers Getting Started, every node type, reference topics (Expression DSL, workflow structure, webhooks, SSE streaming, AI Assistant, Chat with Docs, Portal, security, etc.), and all dashboard tabs (Workflows, Templates, Variables, Chat, Credentials, Vectorstores, MCP, Traces, Alerts, Analytics, Evals, Teams, Logs and more).

Use Chat with Docs from the documentation header for questions grounded in the current article. Ctrl+K opens search, navigation, and workflow actions from the command palette.

Heym is source available under the MIT License with the Commons Clause condition. You can use, modify, distribute, and self-host it under those terms. Commercial licensing is available for rights restricted by the Commons Clause, including selling products or services whose value derives substantially from Heym. See both license files for the full terms.

Join our Discord to connect with the community, ask questions, share workflows, and stay up to date:

Want to publish a workflow template for the community? Submit it directly from the Templates page: open the dialog, paste your workflow DSL, and send it for review. No pull request needed.

If you'd rather contribute through code, please start a Discussion so we can talk it through together before opening a pull request.

Heym is built for developers who want control and enterprise teams that need a trusted path to production. Star Heym ⭐ on GitHub to follow releases and help more builders discover it.

Commercial licensing, deployment services, and professional support help teams build and operate agentic systems on private infrastructure.

What we offer:

• Commercial licensing for your product or service
• Deployment planning, architecture reviews, and infrastructure support
• Custom integrations and feature development
• Assistance with enterprise security and identity requirements
• Onboarding, training, troubleshooting, and solution support
• Priority support and SLA agreements

Core runtime capabilities, including execution history, observability, evals, team controls, SSO, load distribution, and Portal, are part of the self-hosted product.

📧 Contact: enterprise@heym.run