Getting started / Add-Ons /
Amp Orb Provider

Amp Orb Provider

Overview

The Amp Orb Provider add-on runs a self-hosted Amp Orb provider inside your Tapitalee application. Amp sends orb requests to the provider, which launches each orb on its own EC2 instance in your AWS account, in the app’s region and internal network.

How It Works 

Amp → Orb Provider (container) → EC2 instances (one per orb) in your app's VPC
  1. Provider Container: A small utilitycontainer process runs orb-ec2 serve as part of your app and connects to Amp using your runner ID and provider token
  2. IAM Role: A dedicated IAM role lets the provider launch, stop, image, and terminate EC2 instances. It is restricted to resources tagged with amp-orb-provider
  3. Orb Instances: Each orb runs on its own EC2 instance in the app’s internal network, optionally on arm64 (Graviton) and/or spot instances
  4. Status Page: The container serves an unauthenticated status page on port 80, reachable only on the internal network

Purpose and Benefits

  • Runs in Your Account: Orbs run on EC2 instances in your own AWS account and VPC
  • Internal Network Access: Orbs can reach your app’s internal services, such as databases and caches
  • Cost Control: Use spot instances and/or arm64 (Graviton) instances to reduce compute costs
  • Scoped Permissions: The provider’s IAM role can only manage EC2 resources tagged for the provider

Prerequisites

  1. An Amp account with access to Orbs
  2. An orb provider from Amp, under Settings → Orbs → Add Orb Provider, which gives you:
    • The runner ID (AMP_RUNNER_ID)
    • The provider token (AMP_ORB_PROVIDER_TOKEN, starting with aop_live_)

CLI Usage

Create Amp Orb Provider

Create an Amp Orb Provider add-on that runs self-hosted Amp Orbs on EC2 instances in the app’s region and internal network

tapit create amp_orb_provider runner_id=ID amp_orb_provider_token=TOKEN [arm64=true|false] [use_spot=true|false] [description=DESCRIPTION] [--ignore-existing]

Parameters

  • runner_id: Amp runner ID (AMP_RUNNER_ID)
  • amp_orb_provider_token: Amp orb provider token (AMP_ORB_PROVIDER_TOKEN), stored as a secret
  • arm64: Run orbs on arm64 instances (true/false, default false)
  • use_spot: Run orbs on spot instances (true/false, default false)
  • description: Description of the add-on’s purpose
  • --ignore-existing: Skip creation if the app already has an Amp Orb Provider with the same runner_id (useful for idempotent scripts)

Examples 

# Create with default x86_64 on-demand instances
tapit create amp_orb_provider runner_id=RUNNER_ID amp_orb_provider_token=aop_live_abc123...

# Create using arm64 spot instances
tapit create amp_orb_provider runner_id=RUNNER_ID amp_orb_provider_token=aop_live_abc123... arm64=true use_spot=true

Update Amp Orb Provider

Update settings for an existing Amp Orb Provider add-on

tapit set amp_orb_provider name=addon_name [runner_id=ID] [amp_orb_provider_token=TOKEN] [arm64=true|false] [use_spot=true|false] [description=DESCRIPTION]

Parameters

  • name: Name of the Amp Orb Provider add-on to update (required)
  • runner_id: Amp runner ID (AMP_RUNNER_ID)
  • amp_orb_provider_token: Amp orb provider token (AMP_ORB_PROVIDER_TOKEN), stored as a secret
  • arm64: Run orbs on arm64 instances (true/false, default false)
  • use_spot: Run orbs on spot instances (true/false, default false)
  • description: Description of the add-on’s purpose

Examples 

# Switch orbs to spot instances
tapit set amp_orb_provider name=amporb-a1b2c3 use_spot=true

# Rotate the provider token
tapit set amp_orb_provider name=amporb-a1b2c3 amp_orb_provider_token=aop_live_def456...

Changing settings redeploys the provider container.

List and Show

List all add-ons attached to the app with their state and configuration

tapit list addons [-w|--wait]

Parameters

  • -w|--wait: Wait until all add-ons reach a stable state (fully ready or fully deleted); exits non-zero if any add-on is in a failed state

Show detailed information about a specific add-on

tapit show addon name=addon_name

Parameters

  • name: Name of the add-on to show (required)

Delete Amp Orb Provider

Delete an add-on and all its associated AWS resources

tapit delete addon name=addon_name

Parameters

  • name: Name of the add-on to delete (required)

Web UI

You can also manage Amp Orb Provider add-ons through the Tapitalee web interface:

  1. Navigate to your app
  2. Go to the Add-ons section
  3. Click “Add Add-on” and select “Amp Orb Provider”
  4. Enter your runner ID and provider token, and optionally enable arm64 and/or spot instances
  5. Click Create

The add-on’s page lists its current orb EC2 instances and AMIs, refreshed every 30 seconds. The Delete all button launches a background task that terminates all orb instances and deletes all AMIs for this provider.

Only one Amp Orb Provider add-on can exist per app.

Environment Variables

The provider container receives these variables:

Variable Description
AWS_REGION The app’s AWS region
AMP_RUNNER_ID The configured runner ID
AMP_ORB_PROVIDER_TOKEN The provider token (internal secret variable)
ORB_EC2_PROVIDER Identifier used to tag this provider’s EC2 resources
ORB_EC2_ARM true if orbs run on arm64 instances
ORB_EC2_SPOT true if orbs run on spot instances

The app must not already have its own AMP_ORB_PROVIDER_TOKEN variable.

Security Considerations

  • Secret Storage: The provider token is stored as an internal secret variable and is not shown after creation. Leave it blank when editing in the web UI to keep the existing token.
  • Scoped IAM Role: The provider can only start, stop, image, or terminate instances, and delete AMIs, that are tagged with amp-orb-provider.
  • Internal Status Page: The status page on port 80 has no authentication. It is only reachable from the app’s internal network.

Deleting the Add-On

Deleting the add-on first runs a background task that terminates all of the provider’s orb instances and deletes its AMIs. It then removes the provider container, the IAM role, and the AMP_ORB_PROVIDER_TOKEN secret.