Running & Deployment

Heym provides two scripts for different environments: run.sh for local development and deploy.sh for production deployments using Docker Compose.

Video walkthrough: Set Up Heym Locally in Under 2 Minutes — clone the repository, start PostgreSQL, fill in the required environment variables, and create your first account on a local instance.

Prerequisites

Both scripts require the following tools to be installed:

Environment Setup

Both run.sh and deploy.sh read from a .env file in the project root. If it does not exist, the script automatically creates one from .env.example — for both local development and production.

SECRET_KEY and ENCRYPTION_KEY ship empty in .env.example. When either is empty, run.sh and deploy.sh generate a cryptographically strong value automatically and write it back to .env, so a fresh setup needs no manual key handling. If an existing .env still contains the legacy ENCRYPTION_KEY placeholder (change_this_to_a_random_32_byte_hex_value), the scripts stop with an explicit error instead of overwriting it — rotating that key would make previously-encrypted credentials unreadable. The backend itself also refuses to start if either key is empty or left at a known placeholder.

To create the file manually (optional — the scripts do this for you):

cp .env.example .env

Key environment variables:

For every supported variable, default, and production note, see Environment Variables.

Database connection defaults (POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB) are documented in Environment Variables and .env.example.

Development: run.sh

run.sh starts all three services locally — the database (as a Docker container), the FastAPI backend, and the Vite dev server — with a single command.

./run.sh

What it does, step by step:

1. Checks that docker, bun, and uv are available
2. Creates .env from .env.example if missing, and generates a random SECRET_KEY and ENCRYPTION_KEY when either is empty
3. Starts (or creates) a database Docker container on port 6543
4. Installs Python dependencies via uv sync
5. Runs Alembic database migrations (alembic upgrade head)
6. Frees the backend and frontend ports if occupied
7. Starts the FastAPI backend with --reload (hot-reload on code changes)
8. Installs frontend dependencies via bun install
9. Starts the Vite dev server

Options:

Service addresses (dev):

Press Ctrl+C to gracefully stop all services.

End-to-End Tests: run_e2e.sh

The frontend Playwright suite runs against the real Vue application, FastAPI backend, and an isolated PostgreSQL database:

./run_e2e.sh

The suite is a key-path smoke and regression suite, not exhaustive product coverage. It covers authentication, core workflow lifecycle and execution, selected dashboard resources, public routes, and a mocked HITL review UI. Provider integrations, every node type, sharing/permission matrices, and full HITL resume execution remain covered primarily by backend tests or require dedicated integration environments.

Each run gets its own temporary PostgreSQL 16 container, random available database/backend/frontend ports, authentication state, test results, and HTML report. This allows multiple run_e2e.sh processes to run concurrently without sharing state or overwriting artifacts. The script removes its database container when the run finishes and prints the artifact directory and report path.

Useful commands:

./run_e2e.sh --ui         # Interactive Playwright runner with an isolated database
cd frontend
bun run test:e2e:report   # Open the most recently completed local run

Direct bun run test:e2e and bun run test:e2e:ui runs require an explicit DATABASE_URL so they cannot silently start against the local development database. Use ./run_e2e.sh for normal local runs.

./check.sh runs lint, typecheck, formatting, and backend tests without the E2E suite, keeping the default local check path fast. Run Playwright E2E tests separately with ./run_e2e.sh. Pull requests always run the Chromium E2E suite in GitHub Actions and retain traces, screenshots, videos, and the HTML report when failures occur.

Production: deploy.sh

deploy.sh builds and runs the full stack using Docker Compose. All three services — the database, the backend, and the frontend — run as containers. The backend entrypoint automatically runs migrations before starting the server with 8 workers.

Initial deploy (build + start):

./deploy.sh

This performs a zero-downtime deploy: images are built first while the existing containers keep running, then the new version is swapped in.

Available commands:

Service addresses (production):

The frontend container is exposed on FRONTEND_PORT (default: 4017). The backend API is served under the /api path, proxied through the frontend container — so there is only one public-facing port in production.

Container overview:

Version update badge:

The app header shows the running Docker build version. When that version is behind the latest Heym GitHub release, a purple Update badge appears next to the version. Click the version or badge to open the Heym GitHub releases page.

Prebuilt Image: docker run

If you prefer not to build the app locally, you can pull the published container image and run it directly.

The image starts the frontend and backend together in one container. PostgreSQL is still external, but you can provide either DATABASE_URL or the POSTGRES_* variables from .env.example.

Vector store backend. run.sh and deploy.sh run the official postgres:16 image and auto-install the postgresql-16-pgvector package at startup, so the Postgres (pgvector) RAG backend works out of the box there with no change to your data. The prebuilt single-container image, however, connects to a PostgreSQL you provide — that database must support the vector extension to use the Postgres backend. Heym cannot install pgvector into a database it does not manage. Without it, the startup migration skips the pgvector table gracefully — the deploy still succeeds, Qdrant RAG keeps working, and creating or uploading to a Postgres vector store returns a clear "backend unavailable" message until pgvector is enabled.

Set the keys yourself for direct image runs. Unlike run.sh/deploy.sh, the prebuilt image does not auto-generate keys. After cp .env.example .env, populate the two empty keys (replacing in place avoids 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 pull ghcr.io/heymrun/heym:latest
 
docker run --rm \
  --env-file .env \
  -p 4017:4017 \
  -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 \
  ghcr.io/heymrun/heym:latest

Make the file and plugin mounts absolute. FILE_STORAGE_DIR and HEYM_PLUGINS_DIR default to the relative paths ./data/files and data/plugins, and the release image starts the backend from /app/backend. Left relative, they resolve to /app/backend/data/files and /app/backend/data/plugins, so the two bind mounts above receive nothing and uploads are lost when the container is replaced. The -e flags override the relative values .env.example supplies through --env-file, because command-line -e wins over --env-file. Compose (./deploy.sh) does not need this: that image runs the backend from /app, where the relative defaults already land on the mounts.

Docker socket access. Mounting /var/run/docker.sock gives the backend broad control over the host Docker daemon. The default Docker Compose service and the direct docker run example include it for Docker-based MCP stdio tools that run docker commands. The Logs tab still requires DOCKER_LOGS_ENABLED=true and DOCKER_LOGS_ALLOWED_EMAILS with a comma-separated list of trusted user emails. Create the trusted admin account before enabling Docker logs, or keep ALLOW_REGISTER=false, so an unverified self-registration cannot claim an allow-listed email. User-defined Python tools do not get this socket: they run in a separate hardened container with no Docker socket. See Security.

Codex runner. The Codex node uses the same ghcr.io/heymrun/heym image as a sibling runner container (--entrypoint codex) so Codex's Linux sandbox can create namespaces. Keep the heym-codex-workspaces volume mount if you want Codex workflows in the direct image setup; the runner does not receive the Docker socket or backend secrets.

Skill sandbox. Python skills on the Agent node run in a hardened sibling container that shares the heym-codex-workspaces volume, so keep that volume mount for skills too — not just Codex. Each run gets an isolated per-run subpath, and the sibling receives neither the Docker socket nor backend secrets. This needs Docker Engine 25.0+; on older engines, or without the volume, HEYM_PYTHON_TOOL_SANDBOX=auto fails closed — set HEYM_PYTHON_TOOL_SANDBOX=subprocess only for trusted single-user setups. See Security.

Playwright Run Code. Custom Playwright Python needs HEYM_PLAYWRIGHT_CUSTOM_CODE_ENABLED=true and the Docker socket mount above. The release image sets HEYM_PLAYWRIGHT_SANDBOX_IMAGE / HEYM_PLAYWRIGHT_SANDBOX_PYTHON for the GHCR layout (/app/backend/.venv). Compose ./deploy.sh defaults the sandbox image to heym-backend:local. Keep --no-sandbox in Chromium launch args inside sandbox containers.

Minimum environment variables for direct image runs:

Notes:

• The image exposes port 4017
• The backend stays internal and is proxied under /api
• When POSTGRES_HOST=localhost, the release image automatically rewrites it to host.docker.internal when needed so the same .env works with a host-level PostgreSQL container on macOS Docker/Desktop tools
• Keep the data/files mount if you want Drive uploads and skill-generated files to survive container restarts
• Plugins: to enable them, set HEYM_PLUGINS_ENABLED=true and HEYM_PLUGIN_ADMIN_EMAILS, and mount data/plugins so installed plugin files persist across container recreates. Plugin metadata lives in your PostgreSQL, so it also survives. A plugin's declared pip dependencies are installed into the container at install time; because the image filesystem is ephemeral, they are reinstalled automatically on startup for every installed plugin (the release image's uv venv is writable, so this works in the single-container image too)

Common Workflows

First-time setup:

./run.sh          # development — creates .env from .env.example and generates SECRET_KEY/ENCRYPTION_KEY automatically
# or
./deploy.sh       # production — same automatic .env and key generation

For the prebuilt docker run image, generate the keys manually first (see the Prebuilt Image section above).

Update production after a code change:

git pull
./deploy.sh       # rebuilds images, zero-downtime swap

Check production logs:

./deploy.sh --logs

Stop production services:

./deploy.sh --down

Related

• Introduction – Platform overview
• Quick Start – Build your first workflow
• Environment Variables – Full configuration reference
• Security – JWT, encryption, and CORS settings