How a customer runs the executor on THEIR hardware while the graph stays on the hub. Architecture and boundaries: SCALING.md § External / BYO executor. This page is the operational checklist — the hub operator’s half, then the customer’s half.
The shape in one paragraph: the org’s graph lives on the hub, and the hub
keeps serving its storage plane (editor, CRUD, export, diff/merge) as for
any tenant. What the hub refuses for a byo org is execution —
/api/execute*, mutating /api/services calls, and the org’s FaaS app
traffic all answer 421 Misdirected Request. The customer’s own executor
bootstraps the org’s graph over HTTP (GET /api/export/graph-rows), compiles
it in memory, serves the org’s app handler, and stays fresh over the hub’s
SSE relay. It never writes: authoring stays in the hub editor.
The flip is org-granular: it moves ALL of the org’s execution, not one service. A customer who wants “this one app on my hardware, the rest hosted” gets a SECOND org for the self-run app (accounts can belong to several orgs) and flips only that one — see SCALING.md § Boundaries.
Prerequisites: the tenancy addon is enabled (multi-tenant cloud), and the
org is on a paid tier — the byo flip is tier-gated (network /
dedicated; tenancy.plan :byo-allowed?). Flipping a free org fails with
:org/byo-tier-required.
GRAPHDEN_SSE_PORT
(Helm: sse.enabled=true — adds the env, the container port, and a
dedicated <release>-sse Service). The relay speaks plain HTTP;
terminate TLS at the ingress/LB in front of it and raise its
idle-timeout — subscribers hold long-lived streams.POST /api/orgs/plan {name, plan=network}.POST /api/my-tokens (label it, scope it — the executor only
READS, so an execute/write-free scope set is right). The token is the
ACCOUNT’s, and an account belongs to several orgs (its personal one at
least): the executor names its org with GRAPHDEN_EXECUTOR_ORG, sent on
every hub call as the org selector, so the bundle and the SSE stream are
that org’s whichever other orgs the account is in. On a bare
self-hosted hub (no accounts/tenancy) the single AUTH_TOKEN plays this
role instead.POST /api/orgs/execution-mode {name,
execution-mode=byo} (platform-only). The byo memo is dropped in the
same call, so hosted pods start refusing the org’s execution at once.
Flip back with execution-mode=hosted any time — no tier needed for
the way back.The BYO entrypoint lives in the standard executor image/jar — it is the same artifact with a different main class.
From the jar / a checkout:
GRAPHDEN_HUB_URL=https://hub.example.com \
GRAPHDEN_SSE_URL=https://sse.hub.example.com \
GRAPHDEN_EXECUTOR_TOKEN=<the minted bearer> \
GRAPHDEN_EXECUTOR_ORG=acme \
GRAPHDEN_APP_HANDLER_FN=<the org's app handler fn> \
GRAPHDEN_PORT=8080 \
clojure -M -m graphden.byo
From the Docker image, override the CMD (the image’s default CMD boots the
full hub server — a BYO pod wants the graphden.byo main):
# docker-compose.byo.yml — a minimal single-container BYO deployment
services:
byo-executor:
image: graphden-executor:latest
command: ["java", "-cp", "executor-server.jar", "clojure.main", "-m", "graphden.byo"]
ports: ["8080:8080"]
environment:
GRAPHDEN_HUB_URL: https://hub.example.com
GRAPHDEN_SSE_URL: https://sse.hub.example.com
GRAPHDEN_EXECUTOR_TOKEN: ${BYO_TOKEN}
GRAPHDEN_EXECUTOR_ORG: acme
GRAPHDEN_APP_HANDLER_FN: my-app-handler
GRAPHDEN_PORT: "8080"
mem_limit: 2g
No Postgres, no vault, no volumes — the whole state is the in-memory graph snapshot, refetched from the hub.
Environment reference: DEPLOYMENT.md § BYO entrypoint.
If the hub offers no SSE relay, set GRAPHDEN_REFRESH_POLL_MS (e.g.
30000) — without either the graph freezes at the bootstrap snapshot and
the log carries a loud WARN.
RemoteStorage bootstrapped with row counts, then
BYO executor serving.curl http://localhost:8080/ answers with the org’s app.RemoteStorage refreshed (SSE push or the next poll tick) and the next
request serves the change.RemoteStorage refreshed log is
the ground truth.)| Symptom | Meaning | Fix |
|---|---|---|
Bootstrap GET /api/export/graph-rows → 401 |
Bad/expired token | Re-mint via /api/my-tokens; check the Bearer prefix isn’t doubled |
Bootstrap → 421 |
Should not happen since the 2026-08 fix — the hub’s byo refusal is execute-only | Upgrade the hub; export/editor requests must be served for byo orgs |
Hub editor Run popover → 421 |
Expected: execution on hub compute is exactly what the byo flip opts out of | Run through your executor’s app endpoint |
BYO executor started WITHOUT a live-refresh signal WARN |
No SSE url and no poll cadence | Set GRAPHDEN_SSE_URL or GRAPHDEN_REFRESH_POLL_MS |
| Graph serves stale values | SSE stream dropped and nothing re-signalled | The source reconnects with backoff and resyncs on connect; check the LB idle-timeout in front of the relay |
A request logs :execution-error/fn-concealed (the app answers 500 Application error.) |
The app runs — or is built on — a shared fn whose composition the org may not see; the hub ships it signature-only (:concealed? true) and the executor refuses to run it (the error names it in :concealed-fn-id) |
Grant the org :view-impl on that fn’s namespace (then the next refresh ships it whole), or build the app on fns the org owns |
BYO handler fn not found at start |
GRAPHDEN_APP_HANDLER_FN names a fn absent from the org’s branch |
Check the fn name and GRAPHDEN_EXECUTOR_BRANCH |
BYO handler fn name … is defined in several namespaces at start (:byo/ambiguous-handler) |
Names are unique only per namespace, and more than one namespace in the org’s branch defines that name | Set GRAPHDEN_APP_HANDLER_FN to one of the fn ids the message lists |
Execution on a BYO executor is not metered — the hub’s usage metering
counts fn_executions rows in the hub’s Postgres, which a BYO executor
never writes (its storage is read-only), and the hub refuses the org’s
/api/execute anyway. What the org pays for is its paid tier: the storage
plane (editor, branches, export) that keeps living on the hub.