On this page

Helm Charts

The two Helm charts MetaLoom ships — one for the Loom server, one for the Cortex workers — with their values, database options and verification steps.

MetaLoom ships two Helm charts for deploying on Kubernetes — one per component. They live in the helm/ directory of the source repository.

Chart Deploys

helm/loom

The Loom backend server (REST/gRPC/GraphQL API, database access, auth, storage, the pipeline engine, the AI agent) and the bundled web UI. Optionally a self-contained PostgreSQL for quick starts.

helm/cortex

One or more Cortex workers. They register with Loom and run the node tasks it dispatches. The worker image is overridable, so the same chart runs the stock worker or a custom node image.
MetaLoom Helm deployment overview The loom chart deploys the Loom server, a Service, persistent volumes and an optional PostgreSQL. The cortex chart deploys one or more workers that register with the Loom Service over a WebSocket and write results back over REST. helm/loom Deployment · Service · Secrets · PVCs Loom server Deployment + UI Service :8092 · :8091 · :8989 Volumes config · keystore · uploads PostgreSQL bundled — optional helm/cortex StatefulSet — 0..N workers Worker 0 stock image · :8093 Worker N custom image (override) register (WS) tasks · results (REST)

Prerequisites

  • Kubernetes 1.23+ and Helm 3

  • A StorageClass for Loom’s persistent volumes

  • The MetaLoom container images reachable from your cluster (see Container Images)

  • A PostgreSQL database — an external managed one (recommended) or the loom chart’s optional bundled Postgres

Install Loom

For evaluation, let the chart run a self-contained PostgreSQL alongside Loom:

helm install loom ./helm/loom \
  --set postgresql.enabled=true \
  --set auth.initialPassword=<admin-password>

For production, point Loom at an external managed database and expose it through an Ingress:

helm install loom ./helm/loom \
  --set database.host=postgres.internal \
  --set database.name=loom \
  --set database.user=loom \
  --set database.password=<db-password> \
  --set auth.initialPassword=<admin-password> \
  --set ingress.enabled=true \
  --set ingress.host=loom.example.com

Log in to the UI (/ui/) as admin with the password you set.

Tip
 The bundled PostgreSQL uses the official postgres image and is meant for quick starts and evaluation. It is not a managed, backed-up database — run a managed one in production.

Two things a Loom chart must get right

Warning

  • The keystore volume holds the JWT signing key. It is persistent by default and must stay that way. If it is lost on a restart, every token issued beforehand stops verifying and all clients are logged out. The configuration volume (which holds loom.yml) is persisted for the same reason.

  • The coding sandbox is a unit. Setting sandbox.enabled=true renders the runner-namespace role, quota, limits and network policy together with the feature flag. Enabling the flag without that set produces a server that cannot create runner pods, or creates unconstrained ones. Leave it off unless you use the chat agent’s coding sandbox.

Install Cortex

Add one or more workers, pointed at the Loom Service:

helm install cortex ./helm/cortex \
  --set loom.host=loom \
  --set loom.token=<api-token>

Workers dial out to Loom; Loom never connects in to a worker. Scale with replicaCount — each replica registers as its own worker with a stable identity.

Note
 A worker is handed a path to media, not the bytes, so any source/hash/transcription node needs the same media mounted that Loom uses. Enable the media volume (--set media.enabled=true with an existingClaim, hostPath or nfs source) for those workers.

Running a custom node image

The cortex chart’s image.repository value is how you run your own worker — a custom Java daemon or a from-scratch Python worker — instead of the stock one. Build an image from the Cortex examples and point the chart at it:

# A JVM custom worker (built on the stock image; serves the health endpoints):
helm install cortex ./helm/cortex \
  --set image.repository=metaloom/cortex-custom \
  --set loom.token=<token> \
  --set 'nodeKinds={hello-world}'

# A minimal Python worker that does NOT serve a monitoring port — disable the HTTP probes:
helm install cortex-py ./helm/cortex \
  --set image.repository=metaloom/cortex-python \
  --set loom.token=<token> \
  --set readinessProbe.enabled=false \
  --set livenessProbe.type=tcpSocket \
  --set 'nodeKinds={py-hello}'

nodeKinds advertises which node kinds the worker runs. Use command/args if your image needs a different entrypoint and extraEnv for image-specific settings.

Selected values

Table 1. Loom chart
Key Default Purpose

image.repository / image.tag

metaloom/loom-server / chart version

Server image (-native tag for the GraalVM variant).

auth.initialPassword

changeme

Bootstrap admin password. Change it.

database.host / user / password

—

External database connection.

postgresql.enabled

false

Run a bundled PostgreSQL (dev / evaluation).

persistence.keystore / config / uploads

enabled

Persistent volumes (keep keystore + config).

ingress.enabled / host

false / —

Expose the REST/UI port.

ai.enabled / url / modelId

false

Chat agent LLM provider.

sandbox.enabled

false

Coding sandbox + runner-namespace guardrails.
Table 2. Cortex chart
Key Default Purpose

image.repository / image.tag

metaloom/cortex-server / chart version

Worker image — override for a custom one.

loom.host / port

loom / 8092

Loom Service to register with.

loom.token

—

API token for registration and result write-back.

replicaCount

1

Number of workers.

nodeKinds

all

Node kinds this worker advertises.

media.enabled / mountPath

false / /media

Shared source-media mount.

livenessProbe / readinessProbe

httpGet on 8093

Health probes (disable/retype for minimal images).

resources

small

Add limits.nvidia.com/gpu for GPU nodes.

The charts ship a fully commented values.yaml; the READMEs in helm/loom and helm/cortex list every key.

Verify

helm lint ./helm/loom ./helm/cortex
helm template loom ./helm/loom --set postgresql.enabled=true
kubectl rollout status deploy/loom
# Confirm a worker joined the fleet:
kubectl get pods -l app.kubernetes.io/name=cortex

Next steps

Looking for something else?

All documentation Feature overview