Environment Variables

This is the full reference for configuring a self-hosted Heym instance. Every variable is optional unless marked required. Values can be set in a .env file (copy .env.example) or passed directly to the process / container.

./run.sh and ./deploy.sh auto-generate SECRET_KEY and ENCRYPTION_KEY when they are empty, so a plain ./run.sh works with no manual setup.

Defaults below are the values used when the variable is unset. Note that .env.example ships a few tighter starter values (for example shorter JWT lifetimes) that override these code defaults when you copy it.

Required

Rotating ENCRYPTION_KEY

ENCRYPTION_KEY encrypts every stored credential, the SSO client secret and short-lived sign-in state. It can be replaced without downtime and without re-entering credentials. Rotation takes two configuration changes and one admin action, because during a rolling restart old and new configuration run side by side: no process may encrypt with the new key before every other one can decrypt it.

A single container restarts all its processes together, so it can go straight to phase 2. The phases matter for clusters and rolling updates on Kubernetes.

• The re-encryption pauses itself when any live instance encrypts with another key, and says which, so an instance that rolled back can't rotate values back.
• Values no configured key reads (from an earlier key change) are listed in Settings → Encryption, never counted as remaining, so the job can finish. Their owners see them as Unreadable in Credentials, and can enter the value again in place (workflows that use it keep pointing at it) or delete it.
• After phase 3, the old key is refused as ENCRYPTION_KEY. An instance restarted with an old .env fails to start with an error that says so, instead of writing values nobody else can read.

What rotation protects. Rotation protects backups taken afterwards. A leaked key together with a copy of the database still exposes every credential in that copy, so after a leak, also rotate the credentials themselves at their providers.

The key check

Before the server starts, python -m app.key_check compares the keys with a check value stored in the database, and refuses to start with an error naming the cause. The image entrypoints run it after migrations. Worker definitions that start uvicorn directly must run it too: docker-compose.worker.yml, the worker-a service in docker-compose.cluster.yml and deploy/kubernetes/overlays/orbstack-cluster/worker.yaml do, as uv run python -m app.key_check && exec uv run python -m uvicorn …. If you copied one of them before this change, make the same edit. A worker left on the old command still runs without the check, and the cluster still keeps it from receiving work or leading if its keys don't fit.

Only the main instance writes the check value. On its first start after upgrading, it creates it once one of the 20 most recently stored values decrypts, or when there are none. A worker only reads it, and starts without checking until main has written it. If none of them decrypts, because the key was changed at some point and nothing has been re-entered since, main refuses to start. If ENCRYPTION_KEY is the key you want to keep, start main once with HEYM_ACCEPT_CURRENT_ENCRYPTION_KEY=true, then remove it. A worker ignores the flag, so a forgotten one can't make the cluster accept a wrong key.

If the check refuses after phase 4, the old key was most likely removed before phase 3 completed: put it back in ENCRYPTION_KEYS_EXTRA, and finish the re-encryption first. Values stored under the lost key stay unreadable and are listed as described above.

Database

Authentication & sessions

Data retention

OAuth (MCP / API clients)

Networking & CORS

Files & storage

MCP (Model Context Protocol)

While the guard is on, MCP HTTP/SSE tool fetches connect directly (they do not honor HTTP_PROXY/HTTPS_PROXY) so the pinned target IP is authoritative, matching the Drive download guard.

Sandbox backend

Every sandbox (Agent Python tools, skills, the Code node and its formatter, file analysis, custom Playwright, MCP stdio, Codex, OpenCode) runs through one sandbox backend: Docker sibling containers, or pods created through the Kubernetes API. Docker stays the default. The per-sandbox variables below (HEYM_PYTHON_TOOL_SANDBOX, HEYM_PLAYWRIGHT_SANDBOX, HEYM_MCP_STDIO_SANDBOX) still choose between a sandbox and subprocess; HEYM_SANDBOX_BACKEND chooses where sandboxes run. All three variables are optional: a Docker deployment needs none of them, and a backend pod with a ServiceAccount picks Kubernetes on its own.

On Kubernetes every sandbox is one pod under Pod Security restricted: non-root, all capabilities dropped, no privilege escalation, RuntimeDefault seccomp, and no ServiceAccount token. It needs Kubernetes 1.30+ and a CNI that enforces NetworkPolicy: before the first sandbox that must be offline, Heym starts a test pod and refuses offline sandboxes if that pod can still connect. A sandbox's workspace is mounted as a subPath of the PersistentVolumeClaim behind the backend's own workspace directory, never the whole claim. With a ReadWriteOnce claim, sandboxes run on the backend's node. HEYM_MCP_STDIO_FILES_VOLUME names a PersistentVolumeClaim there and HEYM_MCP_STDIO_FILES_SUBPATH its subPath; HEYM_MCP_STDIO_FILES_HOST_DIR is refused. Requirements, RBAC and example manifests: deploy/kubernetes.

Custom CA bundles need no extra setting. When SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS or CODEX_CA_CERTIFICATE names a file, every sandbox that receives the variable also gets that file, read-only at the same path. A backend running on the host binds the file itself. A backend in a container or pod copies it to _ca/ under HEYM_CODEX_WORKSPACE_DIR and mounts only that copy, so the workspace volume must be present; without it the sandbox runs without the file and the backend logs a warning.

Playwright custom code sandbox

The Playwright node's Run Code mode (playwrightCode) is off by default. When enabled it runs in a hardened throwaway sibling container (Compose / GHCR) or, for native ./run.sh, falls back to subprocess. Step-based Playwright nodes are unaffected.

Agent Python tool sandbox

Agent skill sandbox

Untrusted Agent Python skills run in a hardened, throwaway sibling container (non-root, cap-drop ALL, no-new-privileges, read-only root fs, resource limits, no Docker socket) selected by HEYM_PYTHON_TOOL_SANDBOX above. Unlike Python tools, skills keep network egress and a per-run writable workspace, shared with the sibling through the same volume the Codex runner uses. Requires Docker Engine 25.0+ (per-run volume-subpath mounts); otherwise auto fails closed.

Code node sandbox

The Code node adds no variables of its own, and deliberately has no subprocess escape hatch. It runs arbitrary user Python with arbitrary dependencies, so it always requires a reachable sandbox backend (Docker or Kubernetes) and fails closed without one — HEYM_PYTHON_TOOL_SANDBOX does not apply to it. Its limits (512m memory, 1 CPU, 256 PIDs, 120s install timeout, 60s execution timeout) are constants in app/services/code_python_executor.py, not configuration.

It reuses existing variables only: HEYM_PYTHON_TOOL_IMAGE then HEYM_CODEX_DOCKER_IMAGE for image resolution (falling back to inspecting the backend's own image), and HEYM_CODEX_WORKSPACE_DIR / HEYM_CODEX_DOCKER_WORKSPACE_VOLUME for the per-run dependency workspace when the backend is containerised. A native run.sh backend needs neither variable: it bind-mounts a local temporary directory instead. Code nodes with an empty requirements.txt mount nothing at all, since the install phase is skipped.

MCP stdio sandbox

The MCP stdio transport starts a server process from a command supplied in the node configuration (Agent MCP connections, the MCP Call node, and the editor's "Fetch tools" preview). That process runs in a hardened, throwaway sibling container rather than on the backend host: non-root, cap-drop ALL, no-new-privileges, read-only root fs, resource limits, and no Docker socket. Network egress is allowed, because npx / uvx must fetch their package and MCP servers exist to call APIs.

HEYM_MCP_STDIO_SANDBOX is deliberately separate from HEYM_PYTHON_TOOL_SANDBOX: an operator who selects subprocess there for Python tool compatibility (as run.sh does automatically for native dev) must not silently lose MCP stdio isolation as a side effect. Unknown values fall back to auto, never to host execution.

A docker run [flags] IMAGE [args] command keeps working: Heym starts IMAGE itself with the hardening applied, carrying over -e, -w and --entrypoint. Flags that would dissolve the boundary (--privileged, --cap-add, --device, --security-opt, --network host, --pid/--ipc/--uts host, --env-file, --volumes-from) are refused with an explanatory error.

Caller-supplied mounts (-v, --volume, --mount, --volumes-from) are refused outright. Validating a mount source is not a winnable game: //var/run/docker.sock survives os.path.normpath because POSIX preserves exactly two leading slashes, and relative paths, symlinks and parent directories each defeat a denylist differently.

No application storage is mounted by default either. The sandbox sees no Heym files unless you name a volume or directory explicitly, and that mount is read-only unless you also opt into writes. The skill/Codex/OpenCode workspace volumes are never auto-mounted: they hold every tenant's workspaces, so exposing one to a single caller's MCP process would be a cross-tenant read. If a file-oriented MCP server (for example @modelcontextprotocol/server-filesystem) needs data, point HEYM_MCP_STDIO_FILES_VOLUME at a volume you scope yourself, optionally narrowing it with HEYM_MCP_STDIO_FILES_SUBPATH.

Inside the container the root filesystem is read-only and /tmp is a throwaway tmpfs, so the sandbox sets HOME and the npm/uv cache directories to paths under /tmp and mounts that tmpfs with exec. Without those, npx and uvx servers cannot run at all: the sandbox user's passwd home is /nonexistent, and Docker applies noexec to every --tmpfs that does not name exec explicitly. Values you set on the connection are applied after these defaults, so you can override them.

The working directory is that same tmpfs, not the runner image's WORKDIR: /app in the backend image is the Heym backend project itself, so a uv run … server would try to sync it and fail on the read-only root filesystem. A docker run IMAGE command keeps its own image's WORKDIR unless it passes -w.

These variables are wired through docker-compose.yml, so setting them in .env works for ./deploy.sh.

Only the env vars set on the connection reach the server. The backend's own environment (SECRET_KEY, ENCRYPTION_KEY, DATABASE_URL, provider API keys) is never forwarded; the MCP SDK supplies a safe default PATH/HOME/SHELL/TERM/USER/LOGNAME set on top.

Operator-only escape hatches. HEYM_MCP_STDIO_SANDBOX=subprocess and HEYM_MCP_STDIO_FILES_HOST_DIR are never settable by a workflow author, only by whoever runs the deployment. Both can remove the isolation this section describes, so treat them as trusted single-user / single-tenant options and leave them unset on anything multi-user.

Docker log access

Plugins (custom nodes)

Codex node

The Codex node runs the OpenAI Codex CLI in an isolated workspace. It needs the codex CLI and git on PATH. Local ./run.sh uses the native codex CLI. Docker deployments use the bundled heym-codex-docker wrapper, which starts a sibling container from the same Heym image so Codex's bubblewrap sandbox can create Linux namespaces outside the backend container. That container also passes --security-opt systempaths=unconfined (Docker Engine 25+). Docker's default masked /proc paths otherwise reject bubblewrap's fresh proc mount, and every Codex command fails with bwrap: Can't mount proc on /newroot/proc: Operation not permitted. Each run mounts only its own workspace and its <workspace>.codex-home directory, never the rest of the workspace volume (Docker Engine 25+ for a named volume). On Kubernetes the run is a restricted pod, where bubblewrap cannot run, so Codex uses --sandbox danger-full-access and the pod is the boundary.

HEYM_CODEX_CLI_VERSION is a Docker build arg (not a runtime env var) that pins the @openai/codex npm version installed into the image. Default latest.

OpenCode Go node

The OpenCode Go node runs the OpenCode CLI (Go) in an isolated workspace against a GitHub repository. It needs the opencode CLI and git on PATH. Local ./run.sh uses the native opencode CLI (host subprocess). Docker deployments use the bundled heym-opencode-docker wrapper, which starts a hardened sibling container from the same Heym image (all capabilities dropped, no-new-privileges, read-only root, resource limits) sharing the workspace named volume. All git/GitHub operations run host-side, so the GitHub token is never placed inside the OpenCode process/container. Each run mounts only its own workspace and its <workspace>.oc-home directory, never the rest of the workspace volume. With a named volume this needs Docker Engine 25+ (volume-subpath).

HEYM_OPENCODE_CLI_VERSION is a Docker build arg (not a runtime env var) that pins the opencode CLI GitHub release installed into the image. Default latest.

OpenTelemetry tracing

Load distribution (multi-instance)

Point a second Heym instance at the same database and it joins as a worker. Background runs are shared between the instances by a percentage set under Settings → Instances. Postgres is the only channel between them: a worker needs no open port and no route back to the main instance.

Two rules the cluster cannot enforce for you:

• SECRET_KEY and ENCRYPTION_KEY must be identical on every instance, except while rotating ENCRYPTION_KEY. A worker with a different ENCRYPTION_KEY cannot decrypt credentials. Heym compares digests of the keys on each heartbeat and marks an instance incompatible when it can't read what main writes, or what main can't read from it, or what another live instance writes. An incompatible instance receives no work and can't become the leader that runs cron and the pollers.
• Point ingress at the main instance only. Round-robining user traffic across instances would send a file upload to one machine and its download to another.

Worker instances also have a different outbound IP than main. Any API that allowlists source addresses sees the new one. sendEmail runs on main for exactly this reason; for the HTTP node, give the cluster one NAT egress address or allowlist every instance.

Credentials from Kubernetes Secrets

Miscellaneous

Frontend build-time

These are read at build time by Vite and baked into the frontend bundle.