Helm values reference

This reference comes from the README of the released Arcade Helm chart version 1.11.2. Later chart releases replace it automatically.

Set these values in a values.yaml file, or pass them with --set, when you install or upgrade the chart. For installation steps, see Self-host Arcade with Helm.

Every configurable value, grouped. Defaults are in values.yaml.

Image pulls

To reuse a pre-provisioned image-pull Secret instead of passing credentials inline:

dockerRegistry:
  existingSecret: my-dockerhub-pull-secret # must already exist, type: kubernetes.io/dockerconfigjson

Support images

Init containers pull two support images. Override the repository to mirror them off Docker Hub for private-registry or air-gapped installs — this is the only way to keep the migration/seed/reconcile Helm hooks off Docker Hub, since Helm doesn’t run post-renderers over hook manifests. Defaults pull from Docker Hub.

Networking

bindAddress controls what the pod listens on; ipFamilyPolicy / ipFamilies control which ClusterIP families the Service exposes. For IPv6 traffic to reach the pods you typically need both — bindAddress: '::' plus a dual-stack policy:

global:
  bindAddress: "::"
  ipFamilyPolicy: PreferDualStack
  ipFamilies: [IPv4, IPv6]

On Linux, :: accepts IPv4 via IPv4-mapped IPv6. The opentelemetry-collector subchart isn’t templated by the parent chart — override its receiver/exporter endpoints to [::]:port directly if you need IPv6 there.

Networking and security

Availability

Jobs

Public catalog

GET /v1/public/tool_catalog and GET /v1/public/tools serve the deployment’s default catalog with no credential and no tenant. They are off by default and only served when you turn them on:

engine:
  publicCatalog:
    enabled: true

Understand what this publishes before enabling it. On Arcade’s hosted platform the “default catalog” is Arcade’s own shipped toolkits. In a self-hosted install it is whatever workers you configured, so turning this on publishes their tool names, descriptions, and input/output schemas to anyone who can reach the engine. It never exposes tenant-scoped toolkits, secret values, OAuth tokens, or per-user readiness — but the operator’s own static workers are fair game. That is why the default is off and why enabling it is a deliberate act.

Once enabled:

• Responses are shared-cacheable for one hour (Cache-Control: public, max-age=3600, must-revalidate) and carry an ETag, so a CDN in front of the engine absorbs the traffic. Nothing in the engine rate-limits these routes; if you expose them to the open internet, put a rate limit at your edge.
• The catalog is built once and reused for engine.publicCatalog.cacheTtl (default 30s), so cost does not scale with request volume. A change to the default catalog becomes visible within that window without any manual step.
• The catalog is populated by arcade reconcile, which the chart runs on install/upgrade (engine.reconcile.enabled). If reconcile has never run the endpoints answer with an empty catalog rather than an error.

To turn it off again, set enabled: false. The endpoints then respond as if they do not exist, and that response is non-cacheable, so caches converge to the off state on their next revalidation rather than serving a prior copy.

Branded catalog through the experience-api

The engine’s two routes carry operational data only — name, description, version, tool_count, and requirements. Icons, labels, categories, and pro/BYOC classifications belong to the design-system catalog. The experience-api serves GET /api/public/tool_catalog and GET /api/public/tools, which merge the two so a docs or marketing page gets one branded read instead of stitching them client-side.

This half is off by default too, and needs both flags on:

engine:
  publicCatalog:
    enabled: true
experienceApi:
  publicCatalog:
    enabled: true

Turning on only one side is a misconfiguration: with just the experience-api flag, the engine refuses the upstream read and the BFF answers 503; with just the engine flag, the engine’s own two routes work and the BFF’s answer 404.

Once both are on:

• Both sources are cached in-process, so a request costs no upstream work during the freshness window. One snapshot feeds both routes, so a toolkit’s tool_count never disagrees with the tools listed for it. limit / offset (both routes) and toolkit (/tools only) match the engine’s public catalog: default limit=100, max 1000. Responses are shared-cacheable (max-age=60, s-maxage=300, stale-while-revalidate=600) and carry an ETag. Like the engine’s routes, nothing here rate-limits anonymous traffic — put a rate limit at your edge.
• A branding-source outage degrades to metadata: null rather than failing the read, so the catalog stays available when the design-system CDN is not.
• Cross-origin reads are allowed from arcade.dev and bosslevel.dev (and their subdomains) without credentials, in addition to whatever CORS_ORIGIN already trusts.
• experienceApi.publicCatalog.metadataUrl and .engineUrl point the two sources at hosts you control. A private deployment that opts in should set metadataUrl, since the default is an Arcade-hosted CDN.
• Each replica holds the whole catalog in memory, and a refresh briefly holds the outgoing snapshot alongside the incoming one. On a large catalog that is tens of megabytes per replica, so check experienceApi.resources.limits.memory (default 512Mi) before enabling.

Gateway API

The chart emits one HTTPRoute per service, attached to a Gateway you manage outside the chart. TLS terminates at the Gateway listener — no TLS config lives on the routes. Controller-agnostic: works with AWS Gateway API Controller, Traefik, Envoy Gateway, and others.

When gateway.parentRefs is empty, no HTTPRoutes render — this is the chart’s out-of-the-box state.

Ingress and TLS (deprecated)

The legacy Ingress path is kept as a fallback during migration. Prefer gateway.* above. ingress.enabled defaults to false; the hostname/subdomain/URL settings remain in use by both paths.

Authentication

Both signing secrets are auto-generated on first install and persisted across upgrades. Point the ExistingSecret fields at a pre-created Secret in the release namespace to source them from an external vault instead.

Upstream IdP (post-install seeding)

A post-install/post-upgrade Job registers the upstream OIDC provider for the user’s organization. On a fresh install (no orgs yet) it bootstraps an organization + project; on subsequent runs it attaches the IdP to the first existing organization.

The Job reads credentials from a Kubernetes Secret named in auth.upstreamIdp.secretName (default upstream-idp-creds). Create it before helm install:

kubectl create secret generic upstream-idp-creds \
  --namespace arcade \
  --from-literal=UPSTREAM_NAME='Acme Okta' \
  --from-literal=UPSTREAM_ISSUER='https://acme.okta.com' \
  --from-literal=UPSTREAM_CLIENT_ID='0oa...' \
  --from-literal=UPSTREAM_CLIENT_SECRET='...'

Gateway login

The Gateway “Arcade Auth” flow (MCP clients with auth_type: arcade_oauth) authenticates via a single platform-wide “static” User Source. By default that row points at the coordinator-hosted Arcade Identity service at {coordinatorBase}/signin/oidc, which federates to the customer’s upstream IdP via the auth.upstreamIdp config above.

Set auth.gatewayLogin.issuer to point the Gateway login flow at an external IdP directly, skipping Arcade Identity. The same Okta (or Auth0, etc.) app used for dashboard SSO can serve both flows — just register both redirect URIs on it:

• {coordinatorBase}/signin/oidc/callback — dashboard SSO
• {coordinatorBase}/oauth2/intermediate_callback — Gateway login

When auth.gatewayLogin.existingSecret is unset (the default), the chart reuses auth.upstreamIdp.secretName and reads the existing UPSTREAM_CLIENT_ID / UPSTREAM_CLIENT_SECRET keys — no extra Secret needed.

When to set a distinct existingSecret: leaving it empty silently reuses auth.upstreamIdp.secretName. That’s the right default when one IdP app serves both flows, but it means rotating auth.upstreamIdp’s Secret will affect Gateway login in lockstep. Set auth.gatewayLogin.existingSecret to a separate Secret when you need independent rotation, distinct IdP apps for SSO vs. Gateway login, a phased IdP migration, or different sub-claim mappings.

URL overrides

Every URL under arcade.* auto-derives from ingress.hostname and ingress.subdomains.*. Override these only for split-horizon DNS or external proxy routing.

Features

Operator RBAC (OpenFGA)

Fine-grained, per-organization authorization. Always deployed and always enforced: the coordinator decides every organization- and project-scoped admin route against this policy decision point, and fails closed — HTTP 503 — when it cannot reach one. There is no configuration in which the platform runs without it, and no legacy membership-check fallback.

[!IMPORTANT] Upgrading a deployment that already has organizations requires a one-time step on chart 1.9.8 before you upgrade to this release. See Upgrading from 1.9.x.

The bootstrap job creates the store and writes the authorization model; the coordinator blocks startup until the store exists and its latest model is the one shipped in the OpenFGA image, then pins that model id for the pod’s lifetime — no manual step, no restart.

Waiting for the model, not just the store, is what keeps an upgrade that adds new relations from crash-looping the coordinator: without it a rolling pod can resolve the store instantly, read the still-current pre-upgrade model, and fail its startup consistency check while the bootstrap job is mid-write. Pinning the id also stops a later write from swapping the model out from under a pod that already booted.

The bootstrap job is a plain Job, not a hook, so it and the coordinator are applied together and converge; helm --wait is safe. Making it a hook would deadlock — hooks are deferred until Deployments are Ready, and the coordinator is not Ready until the job it is waiting on has run.

Upgrading from 1.9.x (operator-RBAC prerequisite)

A fresh install needs nothing here. Organizations created on this release get their authorization grants written as they are created.

An existing deployment does. Organizations created before RBAC became mandatory have no grants, and nothing in this release creates them: the bootstrap job provisions the store and writes the authorization model, not grants. The role-management API cannot bootstrap the first one either, because calling it already requires a grant. Upgrading straight to this release leaves every organization- and project-scoped admin route returning 403/404 to everyone — projects, members, invitations, API keys, user sources, audit logs, billing.

The commands that write those grants do not exist in this release’s coordinator image. They ship in 1.9.8. So the upgrade runs in four steps, in this order:

1. On chart 1.9.8, set rbac.enabled: true and upgrade. 1.9.8 ships it false, so a stock install has no policy decision point at all — no OpenFGA Deployment, no OPENFGA_API_URL — and the backfill below has nothing to write grants into. Wait for the bootstrap Job to provision the store and write the authorization model before continuing.

2. Backfill grants, once per organization. Both commands are dry-run until --commit — run each without it first and read the plan:

   Terminal

   kubectl exec -n <namespace> deploy/<release>-coordinator -c coordinator -- \
     python -m arcade.cli enable-operator-authz --org-id <org-id> --commit
    
   kubectl exec -n <namespace> deploy/<release>-coordinator -c coordinator -- \
     python -m arcade.cli repair-operator-authz --org-id <org-id> --commit

   enable-operator-authz --all covers every organization at once, but refuses unless the operator-authz-new-orgs system flag is already on — set it with python -m arcade.cli set-system-flag first, or enrol one --org-id at a time. repair-operator-authz takes a repeatable --account <uuid> to restrict the grant set; use it when the dry-run plan lists accounts whose access was deliberately revoked.

3. Verify administration works for a non-owner member on 1.9.8.

4. Remove rbac.enabled from your values and upgrade to this release. The chart refuses to render while the key is present, because it is silently ignored otherwise.

If you have already upgraded and are locked out, roll back to 1.9.8, set rbac.enabled: true there, run the backfill, and upgrade again. Writing tuples directly against OpenFGA is break-glass only — see the openfga-tuples runbook.

Raise helm --timeout past the hook waits

Helm’s default --timeout is 5m, but this release’s hooks can legitimately wait longer: the seed-idp hook budgets ~19m for the policy decision point to come up, and a concurrent index build on a large tool_execution can outlast 5m too. Helm kills the release at its own timeout regardless of a Job’s activeDeadlineSeconds, so the release fails while the work is still healthy. Pass --timeout 30m on the upgrade. Raising jobs.activeDeadlineSeconds without raising --timeout widens the gap rather than closing it.

[!WARNING] If you pin rbac.openfga.modelId, clear it before this upgrade. This release adds relations to the authorization model, and a pinned id skips the resolver that waits for the new model — leaving the coordinator asking for relations the pinned model does not define. Leave it empty and the coordinator pins the right id itself.

Dashboard

Engine

OAuth providers

Top-level oauthProviders block. Each entry renders an auth.providers row in the engine config with id: arcade-<id>, provider_id: <id>, and env-var refs <ID>_CLIENT_ID / <ID>_CLIENT_SECRET resolved from the Secret named in oauthProviders.existingSecret. Defaults to empty — operators add only the providers they want to enable.

Per-entry shape:

Create the credentials Secret yourself — the chart doesn’t generate it. Each enabled provider needs two keys: <PROVIDER_ID_UPPERCASE>_CLIENT_ID and <PROVIDER_ID_UPPERCASE>_CLIENT_SECRET.

kubectl create secret generic arcade-engine-oauth-providers -n arcade \
  --from-literal=GOOGLE_CLIENT_ID=<...> \
  --from-literal=GOOGLE_CLIENT_SECRET=<...> \
  --from-literal=GITHUB_CLIENT_ID=<...> \
  --from-literal=GITHUB_CLIENT_SECRET=<...>

Then list the providers in values.yaml (four per-entry shapes shown):

oauthProviders:
  existingSecret: arcade-engine-oauth-providers
  providers:
    - id: google
    - id: github
      description: "Arcade's default GitHub provider" # override titlecase
    - id: dropbox
      enabled: false # row rendered but engine won't initiate flows
    - id: microsoft
      oauth2: # authorize against one Entra tenant instead of /common
        authorize_request:
          endpoint: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize
        token_request:
          endpoint: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
        refresh_request:
          endpoint: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token

Dashboard playground

Workers

workers is a list. Each entry creates its own Deployment, Service, Secret, and HPA. At least one entry must be enabled.

arcadedev/worker runs a supervisor: one isolated runtime per offered toolkit version, so one worker can serve several versions of a toolkit. The supervisor.* keys configure it.

Upgrading from an eager worker

Charts up to 1.11.0 ship arcadedev/worker as the eager image: every toolkit imported into one process. From this release it is the supervisor, so an upgrade changes how each worker pod runs, with no values change needed:

• Tools are served by one child runtime per toolkit version, started on first call or at boot for supervisor.prewarmToolkits. The first call to a cold toolkit waits for its runtime to start.
• The image also carries the pinned older toolkit versions, so one worker serves every version it offers.
• toolPackages (or ARCADE_MCP_TOOL_PACKAGE in extraEnv) still scopes a worker to those toolkits; supervisor.serveToolkits is the supervisor’s own setting.
• WORKERS has no effect and is logged as such; concurrency comes from supervisor.maxChildren.

The eager image last shipped with chart 1.11.0; to keep a worker on it, stay on that chart.

Experience API

experienceApi.oidcDiscoveryUrl

Use when the public issuer hostname isn’t reachable from inside pods (split-horizon DNS). Only the fetch path is rewritten — published URLs in the discovery doc keep using the public hostname. Full URL, ends in /.well-known/openid-configuration. In-cluster example: http://arcade-coordinator:8001/signin/oidc/.well-known/openid-configuration.

Coordinator

Encryption keys

Every encryption key is auto-generated on first install and persisted with helm.sh/resource-policy=keep so it survives an uninstall. Changing a key in place destroys any data it encrypts — only override if you’re sourcing keys from an external vault (cross-cluster / multi-region).

Each field below accepts a pre-existing Kubernetes Secret via its paired *ExistingSecret / *ExistingSecretKey keys. Defaults for the key names are listed; the secret name is empty (and therefore the chart auto-generates the value) unless you set it.

Postgres

directPort takes precedence over any port embedded in host (host:port or a comma-separated list), so a pooled entry’s port never carries into the direct endpoint; leaving both directHost and directPort unset changes nothing.

A directHost set without a directPort inherits port, which is correct when the direct server and the pooler listen on the same port and wrong when they do not. The wait-for-db init container logs the endpoint it is waiting on and where that port came from — Waiting for the PostgreSQL writer at pg-primary.internal:6432/postgres to be ready (from directHost with port 6432 inherited from the pooled endpoint …) — so a wait that never finishes names its own cause. Give directHost its own directPort (or write it as directHost: pg-primary.internal:5432) when the servers differ.

Per-service Postgres endpoints

By default all four Postgres consumers — engine, coordinator, experience-api and openfga — share the endpoint above, each with its own logical database. Any of them can instead point at its own server, with its own credentials:

postgres:
  enabled: false
  host: shared-db.internal # inherited by anything not overridden below
  auth:
    username: arcade
    existingSecret: shared-db-creds
 
engine:
  database:
    name: arcade_engine
    host: engine-db.internal
    port: 6432
    sslmode: verify-full
    auth:
      username: arcade_engine
      existingSecret: engine-db-creds
 
coordinator:
  database:
    host: coordinator-db.internal
    auth:
      username: arcade_coordinator
      existingSecret: coordinator-db-creds
      # experience-api and the coordinator assemble a DSN, so their Secret needs
      # the password URL-encoded as well as raw.
      existingSecretURLEncKey: DB_PASSWORD_URLENC

The same keys are available under engine.database, coordinator.database, experienceApi.database and rbac.openfga.database.

Things to know:

• A per-service host wins over the bundled Postgres, so services can be migrated one at a time.
• Setting host or port flips create to false, and wait-for-db then probes the service’s own database rather than postgres. A different role or sslmode on the same server does not. Set <service>.database.create: true to opt back in.
• A direct endpoint describes one server, so host/port also stop the service inheriting postgres.directHost/postgres.directPort — otherwise it would wait for readiness against, and migrate against, the shared primary. Give a relocated service behind its own pooler its own directHost/directPort. Conversely, <service>.database.directHost: '' keeps a service that has not moved on the pooled host/port even when the global block names a direct endpoint.
• Give openfga a single host. Its entrypoint keeps only the first entry of a comma-separated DB_HOST; rbac.openfga.database.host rejects a list, but one inherited from postgres.host is silently truncated.
• openfga migrate calls createdb regardless of database.create, so its role needs CREATEDB — or set rbac.openfga.database.migrations: false, which now defaults to true, and migrate out-of-band. With migrations on, wait-for-db probes postgres rather than the openfga database, since that same step creates it.
• Endpoint values travel as container env, not via a ConfigMap. The migration Jobs are pre-upgrade hooks: Helm renders their spec from the new revision but resolves referenced ConfigMaps against the cluster, i.e. the previous revision. engine.yaml reads ${env:DB_HOST} and friends for the same reason.
• directHost/directPort reach the engine’s migration Job as --db-direct-host/--db-direct-port arguments instead of through engine.yaml, so a pooled release can adopt a direct endpoint in a single helm upgrade — the hook does not depend on the ConfigMap of the revision it upgrades from.
• Do not adopt this chart version and move a service’s endpoint in the same upgrade. Upgrading from a version that baked the endpoint into engine.yaml means the pre-upgrade hook still reads those old literals, so the engine’s migration would run against the previous server. Upgrade first, then move the endpoint in a second upgrade. Subsequent moves need no two-step.
• Per-service credentials require auth.existingSecret; there is no inline password. The release’s app-secrets Secret is mounted wholesale via envFrom by ten workloads, so a password there would reach every service.
• postgres.caBundle stays global: experience-api honors a single NODE_EXTRA_CA_CERTS, so concatenate multiple CAs into one bundle.

Redis

redis.tls.insecureSkipVerify has no default: with redis.tls.enabled: true the chart refuses to render until it is set. Set false to verify the Redis server certificate, which must be signed by a CA the pods trust. Set true to skip.

Discovery (arcade-discovery subchart)

The optional arcade-discovery subchart adds tool discovery — Condex, hybrid tool retrieval over RediSearch + Postgres — with its own vendored Redis and Postgres. It is off by default; a default install renders no discovery workloads and leaves the platform Redis and Postgres untouched.

GoEmbed is no longer part of it. arcade-discovery 0.13.0 moved the model servers into arcade-inference below, so a discovery install that needs embeddings enables both and points Condex at the inference release.

Configure the subchart itself under the arcade-discovery: key — its full value reference lives in deploy/charts/arcade-discovery/README.md. The chart is fail-closed: opting in requires, at minimum, arcade-discovery.arcade.releaseName (or explicit engine/coordinator URLs), arcade-discovery.condex.catalogSync.secret, and an inference coordinate (arcade-discovery.inference.releaseName, .embeddingModel, .modelRelease). Enabling discovery with no inference endpoint named is refused at render rather than deployed as a Condex that cannot embed.

Inference (arcade-inference subchart)

The optional arcade-inference subchart adds the model servers — GoEmbed (ONNX embeddings, reranking, image embedding and transcription) and, off by default, the LLM proxy. Split out of arcade-discovery in 0.13.0 so they scale, schedule and upgrade on their own cadence: they want GPUs and multi-minute model loads, while Condex wants Redis and Postgres. It is off by default.

Configure it under the arcade-inference: key — see deploy/charts/arcade-inference/README.md. It is fail-closed too: a model delivery source and its release must be named, because a GoEmbed with no weights to load is a pod that passes no probe.

mTLS

Telemetry

Global defaults live under telemetry.* and apply to every service. Operators can override any field per service by setting <service>.telemetryOverrides.* — the override wins over the global value. The engine, coordinator, experience-api, and workers consume this configuration via dedicated ConfigMaps emitting ARCADE_TELEMETRY_* env vars. All workers share one ConfigMap, so their overrides go under workerDefaults.telemetryOverrides; per-worker differences need workers[].extraEnv.

Example — quiet the coordinator while leaving the rest of the stack alone:

coordinator:
  telemetryOverrides:
    logLevel: "warn"
    traces: "none"

Example — fan signals out to separate collectors (logs to a Loki gateway, traces to a Tempo gateway, metrics still to the in-cluster collector):

telemetry:
  otlpEndpoints:
    logs: "http://loki-gateway:4318"
    traces: "http://tempo-gateway:4318"
    # metrics omitted → falls back to telemetry.otlpEndpoint / otelConfig.endpoint

Per-signal endpoints also accept <service>.telemetryOverrides.otlpEndpoints.* when a single service needs to diverge from the global routing.

For any value not listed, see values.yaml.