Skip to main content

​
Run Swarmd in your own cluster

One helm install stands up the entire platform in your cluster: eight backend services, the platform UI, Keycloak and Postgres — all auto-wired from a single values.yaml. Your data, your network, your cluster. Nothing leaves it except a periodic licence check.

Install it

From a licence key to a running platform, step by step.

How licensing works

Your key is also how the cluster authenticates image pulls.

Choose a database layout

One Postgres or one per service — and how to bring your own.

Expose it

Worked examples for Traefik and AWS Load Balancer Controller.

​
What gets deployed

Keycloak is not optional. Every service authenticates against it, and agent credentials are Keycloak service accounts. You can point at your own Keycloak instead of the bundled one — see external Keycloak.

​
Every service runs split

Each of the seven DB-backed services deploys as two workloads plus a Job: This is the default because the combined topology fails quietly: scaling the API to N replicas also runs N copies of every @Scheduled job, so outbox drainers and monitor evaluators race each other. Splitting also stops a slow scheduler starving the API’s thread pool, and moves migrations out of pod startup so a long Flyway run can’t trip readiness on every replica at once. Budget for it — a default install is 18 Deployments (seven core, seven worker, plus gateway, UI, Postgres and Keycloak), on top of the one-shot Jobs. On a laptop, collapse a service back to a single container with services.<name>.worker.enabled=false.

​
The three-state pattern

Every optional component works the same way, which is worth learning once: The install fails loudly if you pick the third state and leave a required external URL empty — you get a named error at render time, not a CrashLoopBackOff twenty minutes later. postgres and keycloak follow the same shape minus the enabled toggle: they’re required, so it’s only ever “ours or yours”.

​
What you need

Any conformant cluster — EKS, GKE, AKS, OpenShift, k3s, or minikube for a first look. You need:
  • A default StorageClass, or a name to set in postgres.storage.storageClass.
  • Enough headroom: roughly 12 GiB / 6 vCPU for the default shape, since every DB-backed service runs a core and a worker pod. Add ~4 GiB if you choose one Postgres per service. Trimming workers off (services.<name>.worker.enabled=false) brings it back under 8 GiB for a laptop trial.
  • Traefik, or AWS Load Balancer Controller on EKS, if you want real hostnames rather than kubectl port-forward. See Ingress — ingress-nginx is not supported.
Nothing exotic. The chart is a plain Helm 3 chart with no subchart dependencies to fetch.
Format LIC- followed by 32 hex characters. It does two jobs: it authenticates the pull of Swarmd’s private container images, and billing-service verifies it periodically to establish your tier.There is no unlicensed install path for this chart, and no self-serve way to get a key — licences are issued per deployment, so self-hosting starts by talking to us. Without a key the cluster cannot pull the images at all.
The cluster needs outbound HTTPS to api.dev.swarmd.ai and to the ECR registry that serves the images. Nothing else leaves your network — no telemetry, no agent traffic, no prompts.Air-gapped? Mirror the images into your own registry and set global.image.registry. Talk to us about offline licence validation.

​
Self-hosted or Cloud?

It is the same platform either way — the same services, the same tiers, the same licence. The only thing that changes is who runs it. Both are licensed, and both are tiered. Choosing self-hosted is an operational decision — where the data sits and who carries the pager — not a smaller product or a cheaper tier.

Self-hosting starts with a conversation

Licences are issued per deployment, so there’s no self-serve path to a key. Tell us the shape of your estate and we’ll size the tier and get you a licence.
Commercial terms for a self-hosted deployment are agreed with us directly rather than through a card form in the product, so billing-service runs its licence backend: your tier comes from the licence, and the self-serve endpoints (checkout, verify, customer-portal) return 503.That is a difference in how you pay, not in what you get. Nothing about the platform’s capabilities is gated on it.

​
Where to go next

1

Install

Quickstart — licence key to running platform.
2

Understand the licence loop

Licence and images — how one key becomes a rotating image-pull credential.
3

Shape it for your estate

Databases · Ingress · Configuration
4

Start from a known-good file

Presets — eight tested values.yaml shapes, from laptop to hardened production.