Self-Hosted Orbs on Kubernetes

Amp’s Helm chart runs self-hosted orbs on GKE, EKS, and AKS. It installs the orb provider and a dispatch program in one pod. Orbs run as gVisor sandboxes on Substrate, an open source sandbox runtime for Kubernetes that the chart installs with the provider.

How the Chart Works

The pod runs two containers. The spawner container runs amp orb provider and receives jobs from Amp. The provider container asks Substrate for a sandbox, which starts as a pod on one of your worker nodes, and saves a paused orb’s disk to your storage bucket, so it can resume on any worker.

1. The amp-orb-provider pod opens an outbound connection to ampcode.com. 2. Amp sends spawn, pause, and resume jobs. 3. The provider requests a sandbox from the Substrate control plane. 4. Substrate starts an orb pod on a worker node. 5. The orb connects back to its thread. 6. Paused orbs are saved to your storage bucket and resumed from it. No inbound ports are needed.

Supported Platforms

The install bundle has the full prerequisites and commands for each platform:

Platform	Worker requirements	Storage
GKE Standard	Container-Optimized OS, Workload Identity, Dataplane V2	Cloud Storage
EKS (standard or Auto Mode) with a separate worker node group or Karpenter pool	Amazon Linux 2023 workers, VPC CNI network policy on	S3 with IRSA
AKS	Ubuntu or Azure Linux 3.0, workload identity, network policy enforcement	Azure Blob

The chart defaults to 16 vCPU and 32 GiB per orb with two spare workers, so size the node pool for the number of orbs you expect to run at once.

Before You Start

Use a dedicated cluster that meets the platform runbook’s prerequisites, and install from a machine with cloud credentials, kubectl, and Helm 3.14 or newer with cluster-admin access. Terraform examples for EKS and AKS are in the bundle.

Set up a provider in Amp first. The chart needs its token.

Network Requirements

In addition to the outbound access every self-hosted orb needs, allow:

Source	Destination	Purpose
Orb provider	`registry.npmjs.org` or your configured npm registry and its package download hosts, HTTPS 443	CLI installation at container startup
Cluster nodes	`us-central1-docker.pkg.dev`, `registry-1.docker.io`, `storage.googleapis.com`	Runtime and image downloads
Cluster nodes	Your storage, cloud API, and identity endpoints	Saved disks and cluster operation

Install with Amp

Run Amp on a machine that can reach your cluster. Download the install bundle:

export AMP_URL=https://ampcode.com
curl -fsSLo bundle.zip "$AMP_URL/docs/orbs/self-hosted/bundle.zip"
unzip bundle.zip
cd amp-self-hosted-orbs
amp

The bundle includes AGENTS.md, this guide, the platform runbooks, a smoke test, and Terraform examples. Then use this prompt:

Help me install self-hosted Amp orbs on <GKE, EKS, or AKS>. Read AGENTS.md and the platform runbook. Confirm the cloud account, region, cluster, snapshot storage, chart version, and egress policy. Have a workspace admin create the provider in Amp and supply its token securely before installing. Stop at the runbook checkpoints. Ask before creating billable resources, changing shared resources, or deleting anything. Never print credentials. Use the Helm chart, not hand-applied chart resources.

Install

Follow gke.md, eks.md, or aks.md in the bundle to create the cluster and storage, then run its helm install command. The provider token is not a chart value: put it in the Kubernetes Secret amp-orb-spawner (key AMP_ORB_PROVIDER_TOKEN) in the release namespace before installing, so Helm, your values files, and your GitOps repository never hold it. For example, once the GKE prerequisites are met:

kubectl create namespace amp-orbs
kubectl -n amp-orbs create secret generic amp-orb-spawner \
  --from-file=AMP_ORB_PROVIDER_TOKEN=/secure/path/provider-token
helm install orb-provider oci://us-central1-docker.pkg.dev/amp-prod-0/orb-provider/chart \
  -n amp-orbs \
  --set cloud=gke --set amp.url=https://ampcode.com \
  --set snapshots.location=gs://<bucket>/amp-orbs/ \
  --wait --timeout 15m

Without --version, Helm installs the latest chart; run helm show chart on the chart URL to see which version that is. The token file must contain only the token. See self-hosted.md in the bundle for the storage identity values EKS and AKS need. To rotate the token, update the Secret and run kubectl -n amp-orbs rollout restart deployment/amp-orb-provider.

To install the CLI from a private npm registry, create a Secret in the release namespace with a .npmrc key that holds the registry configuration and its authentication, and set:

spawner:
  npm:
    registry: https://npm.example.com/repository/npm/
    existingConfigSecret: ampspawner-npm

See “Internal npm registries” in self-hosted.md for what the registry must serve.

Test the Install

Run NAMESPACE=amp-orbs bash ./smoke-test.sh from the bundle. It spawns, pauses, resumes, and deletes an orb.
Create a thread on the provider with your final firewall and proxy rules in place. Run a command and open Files and Changes. Open Terminal and Desktop, start a dev server, and open its portal.
After Amp shows the orb paused, send another message and check that a file you created is still there.

Troubleshoot

If an orb does not start, read both container logs and the thread’s setup log:

kubectl -n amp-orbs logs deploy/amp-orb-provider -c provider
kubectl -n amp-orbs logs deploy/amp-orb-provider -c spawner

If the cause is not on your side, send a bug report from the thread and include the log lines.

Upgrade

The provider keeps its CLI up to date on its own. Upgrade to the latest chart with:

helm upgrade orb-provider oci://us-central1-docker.pkg.dev/amp-prod-0/orb-provider/chart \
  -n amp-orbs --reset-then-reuse-values --wait --timeout 15m

This keeps your configured values. Running orbs are interrupted during the upgrade, so test pause and resume afterwards. After changing the npm config Secret, restart the provider deployment.

Uninstall

Follow the uninstall steps in the platform runbook. Removing the provider from workspace settings does not delete the cluster or its storage.