Configuration
EngineConnection.fromEnvironment() reads:
| Variable | Meaning |
|---|---|
LERTHA_ADDRESS | host:port of the orchestrator; default 127.0.0.1:7233. The same variable the lertha CLI reads. |
LERTHA_NAMESPACE | default default |
The same binary runs against lertha dev on a laptop or the production orchestrator with no
code change. Credentials for an authenticated orchestrator are documented with the
auth work when it ships.
EngineConnection.fromEnvironment().use { connection ->
val orchestrator = connection.orchestrator()
val runner = connection.runner("gateway")
}
EngineConnection.to("lertha-flow:7233", namespace = "lertha") is the explicit form. That is the
production address from an app on LAP; the orchestrator's gRPC port is not public.
Worker Versioning
A runner can declare the Worker Deployment Version it serves. It then receives only work the
orchestrator routes to that version, which is what a
Serverless Worker Deployment needs. connection.runner(queue)
reads:
| Variable | Meaning |
|---|---|
LERTHA_DEPLOYMENT_NAME | the Worker Deployment name, as entered in the UI |
LERTHA_BUILD_ID | the Build ID of this version, as entered in the UI |
LERTHA_VERSIONING_BEHAVIOR | auto-upgrade (default) or pinned |
With neither LERTHA_DEPLOYMENT_NAME nor LERTHA_BUILD_ID set, the runner is unversioned and
takes all work on its Task Queue, as before. Setting only one of them fails at start-up.
The behavior applies to every Workflow the runner registers:
auto-upgrade: a running Workflow moves to the current version at its next step, so Workflow code must stay compatible with runs already in progress.pinned: a running Workflow stays on the version it started on until it completes.
To set the version in code instead, pass it explicitly. An explicit null turns versioning off
whatever the environment says.
val runner = connection.runner(
"gateway",
version = WorkerVersion("gateway", buildId = "2026-09-16.1", behavior = WorkerVersion.Behavior.Pinned),
)
A versioned runner receives work only while its version is current or ramping in its Worker Deployment. Create Worker Deployment in the UI makes the new version current for you; a version you add later takes work once you make it current or start ramping to it. Until then its Workers poll but take nothing.
Data conversion
Inputs and outputs are Kotlin data classes serialised as JSON through Jackson with the Kotlin module registered, so no-arg constructors are not required. Keep payloads small and stable: they are recorded in every run's history.
Secrets
Never in code or in run inputs. Production values come from Doppler into the process environment, the same as the rest of the platform.