Arcade Deploy on your own cluster (Helm)

This page is for platform operators who run Arcade with the Helm chart and want developers to ship custom MCP servers into that installation with arcade deploy. Once you turn deployments on, the Arcade Engine runs each deployed server as a workload in your own cluster. Bundles go to an object store you own, and runner images come from a registry you choose.

Bundles stay in your environment: the chart requires an artifact store (deployments.artifacts.url), and the Arcade Engine publishes bundles only there. Usage-event tracking (usageTracking.enabled) is off by default in the chart. Leave it off so your installation sends no usage events to Arcade.

The deployments.* values first shipped in chart 1.11.0. Use chart 1.11.1 or later: in 1.11.0 you must set deployments.image.repository yourself, or the chart fails to render, and there are no deployments.runtime.* values.

How it works

• A developer runs arcade deploy against your installation. The Arcade Engine publishes the server’s bundle to your artifact store (S3-compatible, GCS, or Azure Blob).
• The Arcade Engine creates the server in the workers namespace (arcade-workers by default). Each deployed server runs as a Kubernetes Deployment of the runner image (arcadedev/runner), one pod by default, and the pod fetches its bundle from the artifact store.
• Every deployed server gets its own NetworkPolicy. It accepts traffic only from the Arcade Engine. Outbound, it reaches the public internet and cluster DNS, but not private address ranges, link-local addresses (including cloud metadata), or the cluster ranges you list, unless you allowlist a range.

The Arcade Engine’s service account gets a namespaced Role in the workers namespace. That Role covers Deployments, Services, Secrets, ServiceAccounts, NetworkPolicies, ResourceQuotas, Leases, read access to pods and pod logs, and read access to pod metrics. Developers never need cluster access. See Engine service account permissions for the full list and the bucket permissions.

Prerequisites

• A working Arcade installation from the Helm chart, with gateway.hostname, ingress.hostname, or deployments.domain set
• A bucket in an S3-compatible store, Google Cloud Storage, or Azure Blob Storage for release bundles
• Credentials for that bucket that the Arcade Engine can pick up from its environment. The Arcade Engine reads them from the ambient cloud credential chain, never from the bucket URL and never from a deploy request. See Bucket credentials.
• Access from your cluster to the runner image, either arcadedev/runner on Docker Hub or a copy in your own registry
• A CNI plugin that enforces Kubernetes NetworkPolicies, so the per-server isolation takes effect

Bucket credentials

The Arcade Engine opens the artifact store with each cloud SDK’s default credential lookup. Give credentials to the Arcade Engine’s ServiceAccount, <release>-engine in the release namespace, or put them in its environment. Pick one method:

The identity you give the Arcade Engine needs to read and write objects in the bucket: it writes each bundle, and the download URL it signs is only valid if that identity can read the object. See Engine service account permissions for the exact permissions. Deployed servers don’t need bucket credentials as long as the Arcade Engine can sign download URLs. See Artifact store.

EKS Pod Identity

EKS Pod Identity needs no chart values. With the EKS Pod Identity Agent  installed, create an IAM role that EKS Pod Identity can assume and associate it with the Arcade Engine’s ServiceAccount. For a release named arcade in the arcade namespace:

aws eks create-pod-identity-association \
  --cluster-name my-cluster \
  --namespace arcade \
  --service-account arcade-engine \
  --role-arn arn:aws:iam::111122223333:role/arcade-engine

See EKS Pod Identity  for the role’s trust policy.

Static keys

Put the keys in a Secret in the release namespace and pass it to the Arcade Engine with engine.extraEnvFrom:

• S3: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
• Azure Blob: AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_KEY. A shared key also lets the Arcade Engine sign download URLs.

kubectl -n arcade create secret generic arcade-bundle-store \
  --from-literal=AWS_ACCESS_KEY_ID=... \
  --from-literal=AWS_SECRET_ACCESS_KEY=...

engine:
  extraEnvFrom:
    - secretRef:
        name: arcade-bundle-store

Workload identity and key files

Set up the identity on the cloud side first, following EKS IRSA , Azure Workload Identity , or GKE Workload Identity  for the Arcade Engine’s ServiceAccount. Then set the matching values:

The identity applies to the Arcade Engine’s Deployment only. The Arcade Engine’s Jobs (migration, gateway bootstrap, worker reconcile) use their own ServiceAccounts. Extra volumes and mounts also go into those Jobs.

EKS IRSA:

engine:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/arcade-engine

Azure Workload Identity. Also name the storage account, with AZURE_STORAGE_ACCOUNT in engine.extraEnv or storage_account= in deployments.artifacts.url:

engine:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: 00000000-0000-0000-0000-000000000000
  podLabels:
    azure.workload.identity/use: "true"

GKE Workload Identity:

engine:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: arcade-engine@my-project.iam.gserviceaccount.com

GCP service account key file, mounted from a Secret named gcp-key with a key.json entry:

engine:
  extraVolumes:
    - name: gcp-key
      secret:
        secretName: gcp-key
  extraVolumeMounts:
    - name: gcp-key
      mountPath: /var/secrets/gcp
      readOnly: true
  extraEnv:
    - name: GOOGLE_APPLICATION_CREDENTIALS
      value: /var/secrets/gcp/key.json

Engine service account permissions

The Arcade Engine’s ServiceAccount, <release>-engine, needs permissions in two places: the workers namespace in your cluster, and the artifact store bucket.

Kubernetes

The chart creates all of this when deployments.enabled is true. You don’t need to add anything. It renders a Role named <release>-engine-workloads in the workers namespace and a RoleBinding with the same name that binds it to the <release>-engine ServiceAccount in the release namespace. The Role applies to one namespace only: the chart creates no ClusterRole, and the Arcade Engine gets no permissions outside the workers namespace.

With deployments.createNamespace: false, the chart doesn’t create the workers namespace, but it still renders the Role and RoleBinding into it. Create the namespace before you install or upgrade.

Bucket

The Arcade Engine performs two operations on the bucket:

• Writes each bundle. On arcade deploy, it uploads the bundle as one object at a key built from the tenant, project, server name, version, and the bundle’s SHA-256. Deploying the same bundle again can write to the same key, so a write can replace an existing object.
• Signs a download URL for each bundle. The Arcade Engine requests a 24-hour expiry, and temporary credentials can shorten it. The deployed server’s pod uses the URL to fetch its bundle. See Artifact store.

The Arcade Engine doesn’t list or delete objects, and it doesn’t read objects itself. It doesn’t remove bundles from the bucket, so apply any retention you want with a bucket lifecycle rule. A signed URL only works if the identity that signed it can read the object, so the identity needs read access in practice. Read access lets a pod download its bundle.

The table lists the permissions each cloud requires for those two calls.

For GCS, the predefined role roles/storage.objectUser on the bucket includes storage.objects.create, storage.objects.get, and storage.objects.delete. Grant roles/iam.serviceAccountTokenCreator on the service account itself to cover iam.serviceAccounts.signBlob. For more on GCS permissions, see IAM permissions for Cloud Storage .

For S3, this policy covers both operations, scoped to one bucket. Replace arcade-bundles with your bucket name:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:AbortMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::arcade-bundles/*"
    }
  ]
}

Enable deployments

deployments:
  enabled: true
  artifacts:
    # s3://, gs:// or azblob://
    url: s3://arcade-bundles?region=us-east-1

helm upgrade arcade \
  oci://public.ecr.aws/s5i6x9d1/charts/arcade \
  --namespace arcade \
  -f values.yaml

Minimal working configuration

This is the only addition a working Arcade install needs to turn deployments on. The rest of the install comes from the Helm chart guide. The hostname must already be set through gateway.hostname, ingress.hostname, or deployments.domain, and the Arcade Engine needs credentials for the bucket as described in Bucket credentials.

deployments:
  enabled: true
  artifacts:
    # S3. For Google Cloud Storage use gs://arcade-bundles,
    # for Azure Blob Storage use azblob://arcade-bundles
    url: s3://arcade-bundles?region=us-east-1

Everything under deployments other than these two values keeps its default. The hostname comes from gateway.hostname or ingress.hostname, so you don’t need deployments.domain.

Configuration

All settings live under deployments.* in the chart values. Leave a value at its default unless you need to change it.

Core settings

Artifact store

Deployed servers’ pods get no bucket credentials: their ServiceAccount mounts no token, and their NetworkPolicy blocks the cloud metadata endpoint. Instead, the Arcade Engine gives each pod a presigned download URL for its bundle when it can sign one:

Arcade will fail to pull the server bundle if the signed URL is invalid. With Azure Workload Identity or GKE Workload Identity, make sure signing works as described above.

Runner image and registry

For a private mirror, push arcadedev/runner to your registry and point the chart at it:

deployments:
  registry:
    server: registry.example.internal
    imagePullSecrets:
      - my-registry-pull-secret

Sizing

Every deployed server gets the same size.

With the chart, each pod’s requests equal its limits, so pods run in the Guaranteed QoS class. Each pod also has a fixed ephemeral-storage request and limit of 6Gi, which covers a 5Gi volume for the bundle and its virtual environment.

Workers namespace

To use a namespace you manage yourself, set deployments.createNamespace: false. The chart then adds no default-deny NetworkPolicy, unless you also set deployments.network.defaultDenyExistingNamespace: true. Only do that when the namespace holds nothing but deployed servers.

When the reconciler is on, the Arcade Engine also applies its own ResourceQuota, arcade-deployments-budget, in the workers namespace. It limits pods, limits.cpu, and limits.memory, and the reconciler re-applies it on every pass, so manual edits to it don’t last. A pod has to fit every quota in the namespace.

Size deployments.resourceQuota.hard for the number of servers you expect, at deployments.sizing.cpuLimit and deployments.sizing.memoryLimit each, and make sure your nodes can hold them. If deploys stop creating pods while the chart quota still has room, check arcade-deployments-budget with kubectl -n arcade-workers get resourcequota.

If the chart already rendered its quota, only a helm upgrade with deployments.resourceQuota.enabled: false removes it. The Arcade Engine’s Role can’t delete ResourceQuotas.

Network

external DNS mode also needs a bundle endpoint the pod can reach without cluster DNS. Existing deployed servers pick up a DNS mode change only after a redeploy.

Deploy a server

Developers use the same CLI as on Arcade Cloud. Each developer needs an account and a project in your installation first. They sign in to your installation once, select the project if needed, then deploy from the project directory:

arcade login --url https://arcade.example.com
arcade deploy -e src/my_server/server.py

See Arcade Deploy for signing in, picking a project and deploying, and the CLI cheat sheet for every flag.

• Deploy MCP servers built with the Arcade MCP framework for Python. The Arcade Engine refuses a bundle without a Python project definition or with a missing entrypoint.
• The Arcade Engine refuses a changed redeploy while the previous one is still rolling out.
• The Arcade Engine also refuses a bundle over its 16 MiB limit or one that unpacks past 256 MiB, and discards a virtual environment that the bundle ships. The 16 MiB limit caps the upload request, with a little headroom for encoding. Both limits are built into the Arcade Engine; no chart or configuration value changes them.
• A redeploy that changes the server’s code or secrets replaces the release under the same name and gateway URL. A redeploy of a running release that changes nothing is a no-op. Deploying again after a failed release rolls it out again, even if nothing changed.

For non-interactive CI deploys, set ARCADE_URL and ARCADE_API_KEY (a project API key) in the CI environment, then run arcade deploy. With both set, the CLI skips the saved context and browser sign-in and uses ARCADE_URL directly as the Arcade Engine’s URL, without discovery. This needs arcade-mcp 1.16.0 or later.

Check status and logs

Dashboard and CLI

The Servers page in the dashboard lists deployed servers. A removed server disappears from the list. The Arcade Engine tracks each deployed server in one of these states, and arcade deploy waits for a final one:

From the CLI:

arcade server list
arcade server get <name>
arcade server logs <name> -f

Logs cover the current release. After a crash, they also include the immediately previous instance. Arcade doesn’t keep logs beyond that, so ship pod logs to your own logging stack if you need them longer.

kubectl

Deployed servers are ordinary Kubernetes objects in the workers namespace, so your existing tooling works:

kubectl -n arcade-workers get deployments,pods,services
kubectl -n arcade-workers get networkpolicies -l app.kubernetes.io/managed-by=arcade-engine
kubectl -n arcade-workers get resourcequota

Upgrades

Upgrade the chart with helm upgrade as described in Self-host with Helm. Keep these points in mind:

• Runner image. With deployments.image.tag empty, the runner tag follows the chart’s appVersion. Pin deployments.image.tag to control which runner tag the Arcade Engine configures.
• Private registry. Mirror the new runner tag into your registry before you upgrade.
• Namespace. With deployments.createNamespace: true, Helm keeps the workers namespace and its default-deny NetworkPolicy on uninstall, so deployed servers’ objects aren’t deleted with the release.

Moving deployed servers onto a new runner image

When an upgrade changes the runner image tag, the reconciler moves running deployed servers onto it one at a time. This needs deployments.reconciler.enabled: true.

• On each pass (every 30 seconds), the reconciler starts at most one move, and only when no other move is still rolling out.
• If a server can’t start on the new runner image, the Arcade Engine rolls it back to the previous one and marks it degraded with the message “could not start on the upgraded runtime; the previous runtime is still serving”. If no instance of the server is serving when it’s marked degraded, the reason is “release artifact unavailable” instead. The move then halts: no other server moves onto that image.
• Set deployments.autoRoll: false to defer the move. Deployed servers then stay on the runner image they already run until they’re redeployed.

Troubleshooting

Next steps

• Deploy an MCP server with Arcade Deploy
• Create an MCP Gateway to give clients access to deployed servers’ tools
• Platform architecture