Install the MergeLoom worker

The MergeLoom worker runs the actual AI coding execution path: checkout, context assembly, model execution, validation, repair attempts, and branch push.

For first-run testing, Docker Compose is the recommended path. Use Helm when you are ready to run the worker in Kubernetes.

Start in the customer controller

Worker enrollment values come from the customer controller at https://controller.mergeloom.ai. The local worker UI is only available after the worker is installed.

MergeLoom customer controller worker setup page showing tenant slug and worker enrollment token. — Customer controller: copy the tenant slug and enrollment token into the worker install configuration.

Choose an install path

Path	Use it when	Current status
Docker Compose	You want the fastest first run on a Linux host or VPS.	Public installer: MergeLoom/mergeloom-worker-install.
Helm	You want the worker in Kubernetes.	Public chart: MergeLoom/mergeloom-worker-helm-chart.
Manual container run	You need custom orchestration.	Use the public Compose or Helm install as the reference.

Docker Compose install

From the public worker Compose installer repo:

git clone https://github.com/MergeLoom/mergeloom-worker-install.git
cd mergeloom-worker-install
./install.sh

The first run creates .env from .env.example and stops so you can set the customer values:

JCA_WORKER_CONTROL_PLANE_URL=https://controller.mergeloom.ai
JCA_WORKER_TENANT_SLUG=customer-slug
JCA_WORKER_ENROLLMENT_TOKEN=replace-me
JCA_WORKER_NAME=worker-customer

Then run the installer again:

./install.sh

The installer runs the Compose pull and start commands for you. If you need to do the same steps manually:

cp .env.example .env
docker compose pull
docker compose up -d

It starts:

one worker gateway
one worker executor

The gateway owns:

worker UI
provider setup
local provider config
runtime config
live streams
local audit/run state

Executors poll the control plane for work and run jobs.

Docker Compose values

The required .env values are:

Value	What to enter
`JCA_WORKER_CONTROL_PLANE_URL`	`https://controller.mergeloom.ai`
`JCA_WORKER_TENANT_SLUG`	Copy from the MergeLoom controller worker setup page.
`JCA_WORKER_ENROLLMENT_TOKEN`	Copy from the MergeLoom controller worker setup page.
`JCA_WORKER_NAME`	Use a readable name such as `worker-prod-1`.

Useful optional values:

Value	Default
`JCA_WORKER_UI_BASE_PORT`	`8010`
`JCA_WORKER_IMAGE`	`mergeloom/mergeloom:1.0`
`JCA_PROVIDER_CONFIG_MODE`	`ui`
`JCA_WORKER_RUNTIME_CONFIG_MODE`	`ui`
`JCA_WORKER_ALLOWED_COMMANDS`	`git,rg,pytest,python,python3`
`JCA_WORKER_MAX_REPAIR_ATTEMPTS`	`2`

Docker Compose output

After a successful install, open:

http://127.0.0.1:8010/

If the host is remote, tunnel the worker UI:

ssh -L 8010:127.0.0.1:8010 your-user@your-vps

Then open the same local URL in your browser.

MergeLoom local worker UI home page after a successful Docker Compose install. — Local worker UI: open `http://127.0.0.1:8010/`, or tunnel that port from your VPS, to confirm the gateway is running.

Important worker environment values

The .env file includes:

JCA_WORKER_CONTROL_PLANE_URL=https://controller.mergeloom.ai
JCA_WORKER_IMAGE=mergeloom/mergeloom:1.0
JCA_WORKER_TENANT_SLUG=customer-slug
JCA_WORKER_ENROLLMENT_TOKEN=replace-me
JCA_WORKER_NAME=worker-customer
JCA_WORKER_COUNT=1
JCA_WORKER_UI_BASE_PORT=8010
JCA_PROVIDER_CONFIG_MODE=ui
JCA_WORKER_RUNTIME_CONFIG_MODE=ui
JCA_WORKER_ALLOWED_COMMANDS=git,rg,pytest,python,python3
JCA_WORKER_MAX_REPAIR_ATTEMPTS=2

Do not commit real .env values to source control.

Helm install

Install the public chart from Docker Hub OCI:

helm install mergeloom-worker oci://registry-1.docker.io/mergeloom/mergeloom-worker \
  --version 1.0.1 \
  --namespace mergeloom \
  --create-namespace \
  --set worker.controlPlaneUrl="https://controller.mergeloom.ai" \
  --set worker.tenantSlug="customer-slug" \
  --set worker.enrollmentToken="worker-enrollment-token"

Use helm upgrade --install instead if you are updating an existing worker release.

For production installs, keep sensitive values in a Kubernetes Secret instead of Helm values:

kubectl create namespace mergeloom --dry-run=client -o yaml | kubectl apply -f -

kubectl create secret generic mergeloom-worker-env \
  --namespace mergeloom \
  --from-literal=JCA_WORKER_ENROLLMENT_TOKEN="worker-enrollment-token" \
  --from-literal=JCA_OPENAI_API_KEY="openai-api-key"

helm install mergeloom-worker oci://registry-1.docker.io/mergeloom/mergeloom-worker \
  --version 1.0.1 \
  --namespace mergeloom \
  --create-namespace \
  --set worker.controlPlaneUrl="https://controller.mergeloom.ai" \
  --set worker.tenantSlug="customer-slug" \
  --set secret.existingSecretName="mergeloom-worker-env"

When secret.existingSecretName is set, the chart does not create its own Secret. The gateway and executor pods consume the existing Secret with envFrom.

Add only the keys your worker needs:

JCA_WORKER_ENROLLMENT_TOKEN
JCA_WORKER_CLUSTER_TOKEN
JCA_OPENAI_API_KEY
JCA_ANTHROPIC_API_KEY
JCA_VERTEX_SERVICE_ACCOUNT_JSON
JCA_VERTEX_ACCESS_TOKEN
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN
JCA_AZURE_FOUNDRY_API_KEY
AZURE_CLIENT_SECRET
JCA_AZURE_FOUNDRY_BEARER_TOKEN

For Kubernetes cloud identity, prefer keyless identity where your platform supports it:

Vertex AI on GKE: use providerEnv.vertexAuthMethod: adc and a Kubernetes service account allowed by GKE Workload Identity Federation.
AWS Bedrock on EKS: use providerEnv.bedrockAuthMethod: default_chain and an IAM role through IRSA.
Azure Foundry on AKS: use providerEnv.azureFoundryAuthMethod: workload_identity, an AKS workload identity pod label, and the injected federated token file.

The chart source is public:

git clone https://github.com/MergeLoom/mergeloom-worker-helm-chart.git
cd mergeloom-worker-helm-chart

Validate the chart locally before installing if your platform team wants to review it first:

helm lint .
helm template mergeloom-worker . \
  --set worker.controlPlaneUrl="https://controller.mergeloom.ai" \
  --set worker.tenantSlug="customer-slug" \
  --set worker.enrollmentToken="worker-enrollment-token"

Helm values to review

Key values:

image:
  repository: mergeloom/mergeloom
  tag: "1.0"

gateway:
  replicaCount: 1

executors:
  replicaCount: 1

serviceAccount:
  create: false
  name: ""
  annotations: {}

podLabels: {}
podAnnotations: {}

worker:
  controlPlaneUrl: "https://controller.mergeloom.ai"
  tenantSlug: "demo"
  enrollmentToken: ""
  allowedCommands: "git,rg,pytest,python,python3"
  maxRepairAttempts: 2

secret:
  existingSecretName: ""

providerEnv:
  openaiApiKey: ""
  openaiModel: ""
  anthropicApiKey: ""
  anthropicModel: ""
  vertexAuthMethod: ""
  vertexEndpointMode: ""
  vertexProjectId: ""
  vertexLocation: ""
  vertexModel: ""
  bedrockAuthMethod: ""
  bedrockModelId: ""
  azureFoundryAuthMethod: ""
  azureFoundryModel: ""

The gateway runs provider and runtime configuration in UI-managed mode. Executors read provider and runtime config from the gateway.

providerEnv values are useful for quick tests, but sensitive values in providerEnv are stored in Helm release metadata. For production, prefer secret.existingSecretName. For cloud providers, prefer workload identity or IAM roles over static keys when your Kubernetes platform supports them.

Verify the worker

Use the worker UI and logs.

Docker Compose:

docker compose ps
docker compose logs -f
docker compose logs -f worker-gateway
docker compose logs -f worker-executor-1

Kubernetes:

kubectl get pods -n mergeloom
kubectl logs -n mergeloom -l component=gateway -f
kubectl logs -n mergeloom -l component=executor -f

Confirm:

worker gateway is reachable
executor is registered
provider config page loads
control plane enrollment succeeds
no repeated authorization or polling errors appear