{ "@context": "https://schema.org", "@id": "https://aggr.aymericbeaumet.com/items/ampcode-com/2026-10-22-self-hosted-orbs/#webpage", "@type": [ "WebPage", "ArchiveComponent" ], "articleBody": "You can now self-host [orbs](https://ampcode.com/docs/orbs). You provide the compute and Amp turns it into orbs.\n\nIf you have compute that can\n\n- quickly start new machines\n- put them to sleep and resume them equally fast\n- keep them around for a long time\n- scale them to zero, so no one has to worry about having a lot of them sleeping\n\nthen you are now able to replicate the orb experience within your own infrastructure.\n\n## How It Works\n\nYou run `amp orb provider` inside your infrastructure. The `orb provider` then reaches out to Amp and waits for requests to spawn, pause, or delete orbs. Like this:\n\n![1. amp orb provider opens a connection to ampcode.com. 2. Amp sends events to the provider. 3. The provider spawns an orb per thread. 4. Each orb runs in your infrastructure and connects back to its thread on ampcode.com. No inbound ports are needed.](https://static.ampcode.com/news/self-hosted-orbs-diagram-light.avif)\n\n*How* you satisfy those requests is up to you, because `amp orb provider` will dispatch the requests for orb operations (`spawn` to create or resume orbs, `pause`, and `delete`) to a program that you provide, like so:\n\n```shell-session\n$ amp orb provider ./dispatch.sh\n```\n\nIn that program, you can do whatever works best for your infrastructure. Here are some illustrative examples:\n\nDocker E2B K8s Apple containers Modal Vercel Daytona exe.dev\n\n```bash\n#!/usr/bin/env bash\n# dispatch.sh\nset -euo pipefail\n\ncase \"$ORB_OPERATION\" in\n\tspawn)\n\t\tdocker start \"$ORB_ID\" 2>/dev/null ||\n\t\t\tdocker run --platform linux/amd64 -d --name \"$ORB_ID\" \\\n\t\t\t\t\"$ORB_IMAGE\" sleep infinity\n\t\tdocker exec -d --env ORB_TOKEN \"$ORB_ID\" amp orb bootstrap\n\t\t;;\n\tpause)\n\t\tdocker stop \"$ORB_ID\"\n\t\t;;\n\tdelete)\n\t\tdocker rm -f \"$ORB_ID\"\n\t\t;;\nesac\n```\n\nInstall the E2B CLI and the `e2b` package, set `E2B_API_KEY`, and build a template:\n\n```bash\necho 'FROM us-central1-docker.pkg.dev/amp-prod-0/amp-orb/amp-orb:latest' \\\n > e2b.Dockerfile\ne2b template create amp-orbs --dockerfile e2b.Dockerfile \\\n --cpu-count 4 --memory-mb 8192 --ready-cmd true\nexport E2B_TEMPLATE=amp-orbs\n```\n\n```javascript\n#!/usr/bin/env node\n// dispatch.mjs\nimport { Sandbox } from 'e2b'\n\nconst {\n\tORB_OPERATION, ORB_ID, ORB_TOKEN, AMP_URL, E2B_TEMPLATE,\n} = process.env\nconst metadata = { orbId: ORB_ID }\nconst [existing] = await Sandbox.list({\n\tquery: { metadata, state: ['running', 'paused'] },\n}).nextItems()\n\nif (ORB_OPERATION === 'spawn') {\n\tconst timeoutMs = 60 * 60 * 1000\n\tconst sandbox = existing\n\t\t? await Sandbox.connect(existing.sandboxId, { timeoutMs })\n\t\t: await Sandbox.create(E2B_TEMPLATE, {\n\t\t\tmetadata, timeoutMs, lifecycle: { onTimeout: 'pause' },\n\t\t})\n\tconst envs = { ORB_TOKEN }\n\tif (AMP_URL) envs.AMP_URL = AMP_URL\n\tconst bootstrap = await sandbox.commands.run('amp orb bootstrap', {\n\t\tuser: 'user', envs, background: true, timeoutMs: 0,\n\t})\n\tawait bootstrap.disconnect()\n} else if (ORB_OPERATION === 'pause' && existing) {\n\tawait Sandbox.pause(existing.sandboxId)\n} else if (ORB_OPERATION === 'delete' && existing) {\n\tawait Sandbox.kill(existing.sandboxId)\n}\n```\n\n```bash\n#!/usr/bin/env bash\n# dispatch.sh\nset -euo pipefail\nexport PATH=\"/usr/local/bin:/opt/homebrew/bin:$PATH\"\n\n# \"$ORB_IMAGE\" is the Amp orb image.\n\nids=$(container list --all --quiet)\nexists() { grep -Fxq \"$ORB_ID\" <<<\"$ids\"; }\n\ncase \"$ORB_OPERATION\" in\n\tspawn)\n\t\tif exists; then\n\t\t\tcontainer start \"$ORB_ID\"\n\t\telse\n\t\t\tcontainer run --detach --init --rosetta \\\n\t\t\t\t--platform linux/amd64 --cpus 4 --memory 8G \\\n\t\t\t\t--name \"$ORB_ID\" \"$ORB_IMAGE\" sleep infinity\n\t\tfi\n\t\t# A bare --env NAME copies the value from the host.\n\t\tcontainer exec --detach --env ORB_TOKEN --env AMP_URL \\\n\t\t\t\"$ORB_ID\" amp orb bootstrap\n\t\t;;\n\tpause)\n\t\tif exists; then\n\t\t\tcontainer stop \"$ORB_ID\"\n\t\tfi\n\t\t;;\n\tdelete)\n\t\tif exists; then\n\t\t\tcontainer delete --force \"$ORB_ID\"\n\t\tfi\n\t\t;;\n\t*)\n\t\texit 1\n\t\t;;\nesac\n```\n\n```python\n#!/usr/bin/env python3\n# dispatch.py\nimport os\n\nimport modal\n\n# Needs `pip install modal` plus MODAL_TOKEN_ID and MODAL_TOKEN_SECRET.\nAPP = \"amp-orbs\"\napp = modal.App.lookup(APP, create_if_missing=True)\nsnapshots = modal.Dict.from_name(\"amp-orb-snapshots\", create_if_missing=True)\norb_id = os.environ[\"ORB_ID\"]\n\ntry:\n sandbox = modal.Sandbox.from_name(APP, orb_id)\nexcept modal.exception.NotFoundError:\n sandbox = None\n\nmatch os.environ[\"ORB_OPERATION\"]:\n case \"spawn\":\n if sandbox is None:\n # Modal has no pause, so resume from the last snapshot.\n snapshot = snapshots.get(orb_id)\n if snapshot:\n image = modal.Image.from_id(snapshot)\n else:\n image = modal.Image.from_registry(os.environ[\"ORB_IMAGE\"])\n sandbox = modal.Sandbox.create(\n \"sleep\", \"infinity\", app=app, name=orb_id, image=image,\n cpu=4, memory=(16384, 16384), timeout=24 * 60 * 60,\n )\n # Modal execs run as root; point bootstrap at the image user's home.\n bootstrap = \"setsid amp orb bootstrap /dev/null 2>&1 &\"\n sandbox.exec(\n \"bash\", \"-c\", bootstrap,\n env={\n \"ORB_TOKEN\": os.environ[\"ORB_TOKEN\"],\n \"AMP_URL\": os.environ.get(\"AMP_URL\"),\n \"HOME\": \"/home/user\", \"USER\": \"user\",\n },\n ).wait()\n case \"pause\":\n if sandbox:\n image_id = sandbox.snapshot_filesystem(timeout=120).object_id\n snapshots[orb_id] = image_id\n sandbox.terminate()\n case \"delete\":\n if sandbox:\n sandbox.terminate()\n snapshots.pop(orb_id, None)\n```\n\n```javascript\n#!/usr/bin/env node\n// dispatch.mjs\nimport { APIError, Sandbox, Snapshot } from '@vercel/sandbox'\n\nconst { ORB_OPERATION, ORB_ID, ORB_IMAGE, ORB_TOKEN, AMP_URL } = process.env\nconst credentials = {\n\ttoken: process.env.VERCEL_TOKEN,\n\tteamId: process.env.VERCEL_TEAM_ID,\n\tprojectId: process.env.VERCEL_PROJECT_ID,\n}\n\nif (ORB_OPERATION === 'spawn') {\n\tconst sandbox = await Sandbox.getOrCreate({\n\t\t...credentials,\n\t\tname: ORB_ID,\n\t\t// Copy Amp's image to VCR, then set ORB_IMAGE to its VCR URL.\n\t\timage: ORB_IMAGE,\n\t\tresources: { vcpus: 4 },\n\t\ttimeout: 60 * 60 * 1000,\n\t\tpersistent: true,\n\t\tsnapshotExpiration: 0,\n\t\tkeepLastSnapshots: { count: 1, expiration: 0, deleteEvicted: true },\n\t})\n\tconst setup = await sandbox.runCommand({\n\t\tcmd: '/bin/bash',\n\t\targs: ['-c', 'hostname localhost && mkdir -p /vercel/sandbox'],\n\t\tsudo: true,\n\t})\n\tif (setup.exitCode !== 0) throw new Error(await setup.stderr())\n\tawait sandbox.runCommand({\n\t\tcmd: '/usr/bin/setpriv',\n\t\targs: [\n\t\t\t'--reuid=user', '--regid=user', '--init-groups', '--',\n\t\t\t'/usr/bin/env', `ORB_TOKEN=${ORB_TOKEN}`,\n\t\t\t...(AMP_URL ? [`AMP_URL=${AMP_URL}`] : []),\n\t\t\t'HOME=/home/user', 'USER=user', '/bin/bash', '-lc',\n\t\t\t'exec amp orb bootstrap',\n\t\t],\n\t\tsudo: true,\n\t\tdetached: true,\n\t})\n} else if (ORB_OPERATION === 'pause' || ORB_OPERATION === 'delete') {\n\ttry {\n\t\tconst sandbox = await Sandbox.get({\n\t\t\t...credentials, name: ORB_ID, resume: false,\n\t\t})\n\t\tif (ORB_OPERATION === 'delete') {\n\t\t\tif (sandbox.status === 'running') await sandbox.stop()\n\t\t\tfor await (const saved of await sandbox.listSnapshots()) {\n\t\t\t\tif (saved.status !== 'created') continue\n\t\t\t\tconst snapshot = await Snapshot.get({\n\t\t\t\t\t...credentials, snapshotId: saved.id,\n\t\t\t\t})\n\t\t\t\tawait snapshot.delete()\n\t\t\t}\n\t\t\tawait sandbox.delete()\n\t\t} else if (sandbox.status === 'running') await sandbox.stop()\n\t} catch (error) {\n\t\tif (!(error instanceof APIError && error.response.status === 404)) {\n\t\t\tthrow error\n\t\t}\n\t}\n}\n```\n\n```python\n#!/usr/bin/env python3\n# dispatch.py\nimport os\nfrom uuid import uuid4\nfrom daytona import (\n Daytona, DaytonaNotFoundError, CreateSandboxFromImageParams,\n Resources, SessionExecuteRequest, SandboxState,\n)\n\ndaytona = Daytona()\noperation = os.environ['ORB_OPERATION']\ntry:\n sandbox = daytona.get(os.environ['ORB_ID'])\nexcept DaytonaNotFoundError:\n sandbox = None\n\nif operation == 'spawn':\n if sandbox is None:\n sandbox = daytona.create(CreateSandboxFromImageParams(\n name=os.environ['ORB_ID'], image=os.environ['ORB_IMAGE'],\n os_user='user', resources=Resources(cpu=4, memory=8, disk=10),\n auto_stop_interval=0, auto_delete_interval=-1,\n ), timeout=240)\n elif sandbox.state != SandboxState.STARTED:\n sandbox.start()\n env = {key: os.environ[key] for key in ('ORB_TOKEN', 'AMP_URL')\n if key in os.environ}\n sandbox.update_env(env, unset=['AMP_URL'])\n session = str(uuid4())\n sandbox.process.create_session(session)\n sandbox.process.execute_session_command(session, SessionExecuteRequest(\n command=\"bash -lc 'exec amp orb bootstrap'\", run_async=True,\n ))\nelif operation == 'pause' and sandbox:\n if sandbox.state == SandboxState.STARTED:\n sandbox.stop()\nelif operation == 'delete' and sandbox:\n sandbox.delete()\n```\n\n```bash\n#!/usr/bin/env bash\n# dispatch.sh\nset -euo pipefail\n\n# Pause/resume currently requires access enabled by exe.dev support.\nstatus=$(ssh exe.dev ls \"$ORB_ID\" --json |\n jq -r --arg id \"$ORB_ID\" '.vms[] | select(.vm_name == $id) | .status')\n\ncase \"$ORB_OPERATION\" in\n spawn)\n if [[ -z \"$status\" ]]; then\n ssh exe.dev new --name=\"$ORB_ID\" --image=\"$ORB_IMAGE\" \\\n --cpu=2 --memory=8G --no-email\n elif [[ \"$status\" == paused ]]; then\n ssh exe.dev resume \"$ORB_ID\"\n fi\n {\n printf 'export ORB_TOKEN=%q\\n' \"$ORB_TOKEN\"\n if [[ -n \"${AMP_URL:-}\" ]]; then\n printf 'export AMP_URL=%q\\n' \"$AMP_URL\"\n fi\n cat <<'BOOTSTRAP'\nsudo -u user --preserve-env=ORB_TOKEN,AMP_URL bash -lc \\\n 'cd \"$HOME\"; nohup amp orb bootstrap .amp-bootstrap.log 2>&1 &'\nBOOTSTRAP\n } | ssh \"$ORB_ID.exe.xyz\" bash -s\n ;;\n pause)\n if [[ \"$status\" == running ]]; then\n ssh exe.dev pause \"$ORB_ID\"\n fi\n ;;\n delete)\n if [[ -n \"$status\" ]]; then\n ssh exe.dev rm \"$ORB_ID\"\n fi\n ;;\nesac\n```\n\nUse [Amp's Helm chart](https://ampcode.com/docs/orbs/self-hosted/kubernetes#install) to run orbs on **GKE, EKS, or AKS**. Under the hood, it runs `amp orb provider` with a supplied dispatch program that handles spawning, pausing, and deleting orbs. You don't need to write a dispatch script yourself.\n\n1. [Create a custom orb provider](https://ampcode.com/docs/orbs/self-hosted#set-up-a-provider) in your Amp workspace and copy its token.\n2. Prepare a dedicated cluster with [worker nodes and snapshot storage](https://ampcode.com/docs/orbs/self-hosted/kubernetes#supported-platforms). Paused orbs are saved to storage and can resume on another worker node.\n3. [Download the Kubernetes setup files](https://ampcode.com/docs/orbs/self-hosted/bundle.zip). The ZIP includes `gke.md`, `eks.md`, and `aks.md` with the setup and Helm commands for each cloud, plus Terraform examples. Use the instructions for your cloud to install the chart and test your first orb.\n\nThese examples use Amp's pre-built `ORB_IMAGE`, which includes the Amp CLI and other dependencies. You can use a different Linux image as long as you can start `amp orb bootstrap` in it (and [it has the dependencies for other features](https://ampcode.com/docs/orbs/self-hosted#bring-your-own-image)). That process connects the orb to Amp so Amp can set up the environment and run the agent's tools.\n\nOnce you have your dispatch program, go to your workspace settings (individuals can create a workspace for free), add a [**Custom Orb Provider**](https://ampcode.com/workspace#custom-orb-providers), copy the token, and run `amp orb provider`:\n\n```shell-session\n$ chmod +x dispatch.sh\n$ export AMP_ORB_PROVIDER_TOKEN=\"\"\n$ amp orb provider ./dispatch.sh\n```\n\nOnce that runs, open ampcode.com or the Amp macOS or iOS applications and create a new thread. Expand **Orb** and choose your provider under **Self-Hosted**.\n\n![The full new thread composer with the executor picker open and our-k8s-orbs highlighted and selected under Self-Hosted](https://static.ampcode.com/news/self-hosted-orbs-editor-light.avif) ![The full new thread composer with the executor picker open and our-k8s-orbs highlighted and selected under Self-Hosted](https://static.ampcode.com/news/self-hosted-orbs-editor-dark.avif)\n\nAnd then submit your prompt. Amp will send a request to your provider to spawn an orb, clone your repository, run your setup files, and start the agent.\n\nAnd thus begins, as they say, orbin' time. Self-hosted.\n\n## You Probably Shouldn't Self-Host Orbs\n\nAll that said: you probably shouldn't self-host orbs.\n\nWe built self-hosted orbs for enterprises that can't use the orbs we host, because regulations might restrict where their code runs, because they need access to internal networks, or because they need custom hardware attached.\n\nIf you're on an Enterprise plan, let us know and we'll help you set it up.\n\nThat's why the interface is so open: we want to support all the infrastructure our enterprise customers might have, as long as it meets the qualitative requirements above (fast-to-start, resumable machines that scale to zero, etc.). But that also means we only support our end of the contract, not every possible piece of infrastructure you can plug in.\n\n## Pricing\n\nSelf-hosted orbs are free for individuals and teams. Enterprises will be charged [standard orb pricing](https://ampcode.com/docs/orbs/sizes-and-costs) starting October 29. Until then, self-hosted orbs are free for every workspace.\n\n## Getting Started\n\nFor more information on self-hosted orbs and how to run self-hosted orbs on Kubernetes, [see the documentation](https://ampcode.com/docs/orbs/self-hosted).\n", "authors": [], "captured_at": "2026-10-22T17:33:41.202070908+00:00", "category": "programming", "content_html": "

You can now self-host orbs. You provide the compute and Amp turns it into orbs.

\n

If you have compute that can

\n\n

then you are now able to replicate the orb experience within your own infrastructure.

\n

How It Works

\n

You run amp orb provider inside your infrastructure. The orb provider then reaches out to Amp and waits for requests to spawn, pause, or delete orbs. Like this:

\n

\"1.

\n

How you satisfy those requests is up to you, because amp orb provider will dispatch the requests for orb operations (spawn to create or resume orbs, pause, and delete) to a program that you provide, like so:

\n
$ amp orb provider ./dispatch.sh\n
\n

In that program, you can do whatever works best for your infrastructure. Here are some illustrative examples:

\n

Docker E2B K8s Apple containers Modal Vercel Daytona exe.dev

\n
#!/usr/bin/env bash\n# dispatch.sh\nset -euo pipefail\n\ncase "$ORB_OPERATION" in\n\tspawn)\n\t\tdocker start "$ORB_ID" 2>/dev/null ||\n\t\t\tdocker run --platform linux/amd64 -d --name "$ORB_ID" \\\n\t\t\t\t"$ORB_IMAGE" sleep infinity\n\t\tdocker exec -d --env ORB_TOKEN "$ORB_ID" amp orb bootstrap\n\t\t;;\n\tpause)\n\t\tdocker stop "$ORB_ID"\n\t\t;;\n\tdelete)\n\t\tdocker rm -f "$ORB_ID"\n\t\t;;\nesac\n
\n

Install the E2B CLI and the e2b package, set E2B_API_KEY, and build a template:

\n
echo 'FROM us-central1-docker.pkg.dev/amp-prod-0/amp-orb/amp-orb:latest' \\\n    > e2b.Dockerfile\ne2b template create amp-orbs --dockerfile e2b.Dockerfile \\\n    --cpu-count 4 --memory-mb 8192 --ready-cmd true\nexport E2B_TEMPLATE=amp-orbs\n
\n
#!/usr/bin/env node\n// dispatch.mjs\nimport { Sandbox } from 'e2b'\n\nconst {\n\tORB_OPERATION, ORB_ID, ORB_TOKEN, AMP_URL, E2B_TEMPLATE,\n} = process.env\nconst metadata = { orbId: ORB_ID }\nconst [existing] = await Sandbox.list({\n\tquery: { metadata, state: ['running', 'paused'] },\n}).nextItems()\n\nif (ORB_OPERATION === 'spawn') {\n\tconst timeoutMs = 60 * 60 * 1000\n\tconst sandbox = existing\n\t\t? await Sandbox.connect(existing.sandboxId, { timeoutMs })\n\t\t: await Sandbox.create(E2B_TEMPLATE, {\n\t\t\tmetadata, timeoutMs, lifecycle: { onTimeout: 'pause' },\n\t\t})\n\tconst envs = { ORB_TOKEN }\n\tif (AMP_URL) envs.AMP_URL = AMP_URL\n\tconst bootstrap = await sandbox.commands.run('amp orb bootstrap', {\n\t\tuser: 'user', envs, background: true, timeoutMs: 0,\n\t})\n\tawait bootstrap.disconnect()\n} else if (ORB_OPERATION === 'pause' && existing) {\n\tawait Sandbox.pause(existing.sandboxId)\n} else if (ORB_OPERATION === 'delete' && existing) {\n\tawait Sandbox.kill(existing.sandboxId)\n}\n
\n
#!/usr/bin/env bash\n# dispatch.sh\nset -euo pipefail\nexport PATH="/usr/local/bin:/opt/homebrew/bin:$PATH"\n\n# "$ORB_IMAGE" is the Amp orb image.\n\nids=$(container list --all --quiet)\nexists() { grep -Fxq "$ORB_ID" <<<"$ids"; }\n\ncase "$ORB_OPERATION" in\n\tspawn)\n\t\tif exists; then\n\t\t\tcontainer start "$ORB_ID"\n\t\telse\n\t\t\tcontainer run --detach --init --rosetta \\\n\t\t\t\t--platform linux/amd64 --cpus 4 --memory 8G \\\n\t\t\t\t--name "$ORB_ID" "$ORB_IMAGE" sleep infinity\n\t\tfi\n\t\t# A bare --env NAME copies the value from the host.\n\t\tcontainer exec --detach --env ORB_TOKEN --env AMP_URL \\\n\t\t\t"$ORB_ID" amp orb bootstrap\n\t\t;;\n\tpause)\n\t\tif exists; then\n\t\t\tcontainer stop "$ORB_ID"\n\t\tfi\n\t\t;;\n\tdelete)\n\t\tif exists; then\n\t\t\tcontainer delete --force "$ORB_ID"\n\t\tfi\n\t\t;;\n\t*)\n\t\texit 1\n\t\t;;\nesac\n
\n
#!/usr/bin/env python3\n# dispatch.py\nimport os\n\nimport modal\n\n# Needs `pip install modal` plus MODAL_TOKEN_ID and MODAL_TOKEN_SECRET.\nAPP = "amp-orbs"\napp = modal.App.lookup(APP, create_if_missing=True)\nsnapshots = modal.Dict.from_name("amp-orb-snapshots", create_if_missing=True)\norb_id = os.environ["ORB_ID"]\n\ntry:\n    sandbox = modal.Sandbox.from_name(APP, orb_id)\nexcept modal.exception.NotFoundError:\n    sandbox = None\n\nmatch os.environ["ORB_OPERATION"]:\n    case "spawn":\n        if sandbox is None:\n            # Modal has no pause, so resume from the last snapshot.\n            snapshot = snapshots.get(orb_id)\n            if snapshot:\n                image = modal.Image.from_id(snapshot)\n            else:\n                image = modal.Image.from_registry(os.environ["ORB_IMAGE"])\n            sandbox = modal.Sandbox.create(\n                "sleep", "infinity", app=app, name=orb_id, image=image,\n                cpu=4, memory=(16384, 16384), timeout=24 * 60 * 60,\n            )\n        # Modal execs run as root; point bootstrap at the image user's home.\n        bootstrap = "setsid amp orb bootstrap </dev/null >/dev/null 2>&1 &"\n        sandbox.exec(\n            "bash", "-c", bootstrap,\n            env={\n                "ORB_TOKEN": os.environ["ORB_TOKEN"],\n                "AMP_URL": os.environ.get("AMP_URL"),\n                "HOME": "/home/user", "USER": "user",\n            },\n        ).wait()\n    case "pause":\n        if sandbox:\n            image_id = sandbox.snapshot_filesystem(timeout=120).object_id\n            snapshots[orb_id] = image_id\n            sandbox.terminate()\n    case "delete":\n        if sandbox:\n            sandbox.terminate()\n        snapshots.pop(orb_id, None)\n
\n
#!/usr/bin/env node\n// dispatch.mjs\nimport { APIError, Sandbox, Snapshot } from '@vercel/sandbox'\n\nconst { ORB_OPERATION, ORB_ID, ORB_IMAGE, ORB_TOKEN, AMP_URL } = process.env\nconst credentials = {\n\ttoken: process.env.VERCEL_TOKEN,\n\tteamId: process.env.VERCEL_TEAM_ID,\n\tprojectId: process.env.VERCEL_PROJECT_ID,\n}\n\nif (ORB_OPERATION === 'spawn') {\n\tconst sandbox = await Sandbox.getOrCreate({\n\t\t...credentials,\n\t\tname: ORB_ID,\n\t\t// Copy Amp's image to VCR, then set ORB_IMAGE to its VCR URL.\n\t\timage: ORB_IMAGE,\n\t\tresources: { vcpus: 4 },\n\t\ttimeout: 60 * 60 * 1000,\n\t\tpersistent: true,\n\t\tsnapshotExpiration: 0,\n\t\tkeepLastSnapshots: { count: 1, expiration: 0, deleteEvicted: true },\n\t})\n\tconst setup = await sandbox.runCommand({\n\t\tcmd: '/bin/bash',\n\t\targs: ['-c', 'hostname localhost && mkdir -p /vercel/sandbox'],\n\t\tsudo: true,\n\t})\n\tif (setup.exitCode !== 0) throw new Error(await setup.stderr())\n\tawait sandbox.runCommand({\n\t\tcmd: '/usr/bin/setpriv',\n\t\targs: [\n\t\t\t'--reuid=user', '--regid=user', '--init-groups', '--',\n\t\t\t'/usr/bin/env', `ORB_TOKEN=${ORB_TOKEN}`,\n\t\t\t...(AMP_URL ? [`AMP_URL=${AMP_URL}`] : []),\n\t\t\t'HOME=/home/user', 'USER=user', '/bin/bash', '-lc',\n\t\t\t'exec amp orb bootstrap',\n\t\t],\n\t\tsudo: true,\n\t\tdetached: true,\n\t})\n} else if (ORB_OPERATION === 'pause' || ORB_OPERATION === 'delete') {\n\ttry {\n\t\tconst sandbox = await Sandbox.get({\n\t\t\t...credentials, name: ORB_ID, resume: false,\n\t\t})\n\t\tif (ORB_OPERATION === 'delete') {\n\t\t\tif (sandbox.status === 'running') await sandbox.stop()\n\t\t\tfor await (const saved of await sandbox.listSnapshots()) {\n\t\t\t\tif (saved.status !== 'created') continue\n\t\t\t\tconst snapshot = await Snapshot.get({\n\t\t\t\t\t...credentials, snapshotId: saved.id,\n\t\t\t\t})\n\t\t\t\tawait snapshot.delete()\n\t\t\t}\n\t\t\tawait sandbox.delete()\n\t\t} else if (sandbox.status === 'running') await sandbox.stop()\n\t} catch (error) {\n\t\tif (!(error instanceof APIError && error.response.status === 404)) {\n\t\t\tthrow error\n\t\t}\n\t}\n}\n
\n
#!/usr/bin/env python3\n# dispatch.py\nimport os\nfrom uuid import uuid4\nfrom daytona import (\n    Daytona, DaytonaNotFoundError, CreateSandboxFromImageParams,\n    Resources, SessionExecuteRequest, SandboxState,\n)\n\ndaytona = Daytona()\noperation = os.environ['ORB_OPERATION']\ntry:\n    sandbox = daytona.get(os.environ['ORB_ID'])\nexcept DaytonaNotFoundError:\n    sandbox = None\n\nif operation == 'spawn':\n    if sandbox is None:\n        sandbox = daytona.create(CreateSandboxFromImageParams(\n            name=os.environ['ORB_ID'], image=os.environ['ORB_IMAGE'],\n            os_user='user', resources=Resources(cpu=4, memory=8, disk=10),\n            auto_stop_interval=0, auto_delete_interval=-1,\n        ), timeout=240)\n    elif sandbox.state != SandboxState.STARTED:\n        sandbox.start()\n    env = {key: os.environ[key] for key in ('ORB_TOKEN', 'AMP_URL')\n           if key in os.environ}\n    sandbox.update_env(env, unset=['AMP_URL'])\n    session = str(uuid4())\n    sandbox.process.create_session(session)\n    sandbox.process.execute_session_command(session, SessionExecuteRequest(\n        command="bash -lc 'exec amp orb bootstrap'", run_async=True,\n    ))\nelif operation == 'pause' and sandbox:\n    if sandbox.state == SandboxState.STARTED:\n        sandbox.stop()\nelif operation == 'delete' and sandbox:\n    sandbox.delete()\n
\n
#!/usr/bin/env bash\n# dispatch.sh\nset -euo pipefail\n\n# Pause/resume currently requires access enabled by exe.dev support.\nstatus=$(ssh exe.dev ls "$ORB_ID" --json |\n    jq -r --arg id "$ORB_ID" '.vms[] | select(.vm_name == $id) | .status')\n\ncase "$ORB_OPERATION" in\n    spawn)\n        if [[ -z "$status" ]]; then\n            ssh exe.dev new --name="$ORB_ID" --image="$ORB_IMAGE" \\\n                --cpu=2 --memory=8G --no-email\n        elif [[ "$status" == paused ]]; then\n            ssh exe.dev resume "$ORB_ID"\n        fi\n        {\n            printf 'export ORB_TOKEN=%q\\n' "$ORB_TOKEN"\n            if [[ -n "${AMP_URL:-}" ]]; then\n                printf 'export AMP_URL=%q\\n' "$AMP_URL"\n            fi\n            cat <<'BOOTSTRAP'\nsudo -u user --preserve-env=ORB_TOKEN,AMP_URL bash -lc \\\n    'cd "$HOME"; nohup amp orb bootstrap </dev/null >.amp-bootstrap.log 2>&1 &'\nBOOTSTRAP\n        } | ssh "$ORB_ID.exe.xyz" bash -s\n        ;;\n    pause)\n        if [[ "$status" == running ]]; then\n            ssh exe.dev pause "$ORB_ID"\n        fi\n        ;;\n    delete)\n        if [[ -n "$status" ]]; then\n            ssh exe.dev rm "$ORB_ID"\n        fi\n        ;;\nesac\n
\n

Use Amp's Helm chart to run orbs on GKE, EKS, or AKS. Under the hood, it runs amp orb provider with a supplied dispatch program that handles spawning, pausing, and deleting orbs. You don't need to write a dispatch script yourself.

\n
    \n
  1. Create a custom orb provider in your Amp workspace and copy its token.
    2. \n
  2. Prepare a dedicated cluster with worker nodes and snapshot storage. Paused orbs are saved to storage and can resume on another worker node.
    3. \n
  3. Download the Kubernetes setup files. The ZIP includes gke.md, eks.md, and aks.md with the setup and Helm commands for each cloud, plus Terraform examples. Use the instructions for your cloud to install the chart and test your first orb.
    4. \n
\n

These examples use Amp's pre-built ORB_IMAGE, which includes the Amp CLI and other dependencies. You can use a different Linux image as long as you can start amp orb bootstrap in it (and it has the dependencies for other features). That process connects the orb to Amp so Amp can set up the environment and run the agent's tools.

\n

Once you have your dispatch program, go to your workspace settings (individuals can create a workspace for free), add a Custom Orb Provider, copy the token, and run amp orb provider:

\n
$ chmod +x dispatch.sh\n$ export AMP_ORB_PROVIDER_TOKEN="<copied-token>"\n$ amp orb provider ./dispatch.sh\n
\n

Once that runs, open ampcode.com or the Amp macOS or iOS applications and create a new thread. Expand Orb and choose your provider under Self-Hosted.

\n

\"The \"The

\n

And then submit your prompt. Amp will send a request to your provider to spawn an orb, clone your repository, run your setup files, and start the agent.

\n

And thus begins, as they say, orbin' time. Self-hosted.

\n

You Probably Shouldn't Self-Host Orbs

\n

All that said: you probably shouldn't self-host orbs.

\n

We built self-hosted orbs for enterprises that can't use the orbs we host, because regulations might restrict where their code runs, because they need access to internal networks, or because they need custom hardware attached.

\n

If you're on an Enterprise plan, let us know and we'll help you set it up.

\n

That's why the interface is so open: we want to support all the infrastructure our enterprise customers might have, as long as it meets the qualitative requirements above (fast-to-start, resumable machines that scale to zero, etc.). But that also means we only support our end of the contract, not every possible piece of infrastructure you can plug in.

\n

Pricing

\n

Self-hosted orbs are free for individuals and teams. Enterprises will be charged standard orb pricing starting October 29. Until then, self-hosted orbs are free for every workspace.

\n

Getting Started

\n

For more information on self-hosted orbs and how to run self-hosted orbs on Kubernetes, see the documentation.

\n", "content_markdown": "You can now self-host [orbs](https://ampcode.com/docs/orbs). You provide the compute and Amp turns it into orbs.\n\nIf you have compute that can\n\n- quickly start new machines\n- put them to sleep and resume them equally fast\n- keep them around for a long time\n- scale them to zero, so no one has to worry about having a lot of them sleeping\n\nthen you are now able to replicate the orb experience within your own infrastructure.\n\n## How It Works\n\nYou run `amp orb provider` inside your infrastructure. The `orb provider` then reaches out to Amp and waits for requests to spawn, pause, or delete orbs. Like this:\n\n![1. amp orb provider opens a connection to ampcode.com. 2. Amp sends events to the provider. 3. The provider spawns an orb per thread. 4. Each orb runs in your infrastructure and connects back to its thread on ampcode.com. No inbound ports are needed.](https://static.ampcode.com/news/self-hosted-orbs-diagram-light.avif)\n\n*How* you satisfy those requests is up to you, because `amp orb provider` will dispatch the requests for orb operations (`spawn` to create or resume orbs, `pause`, and `delete`) to a program that you provide, like so:\n\n```shell-session\n$ amp orb provider ./dispatch.sh\n```\n\nIn that program, you can do whatever works best for your infrastructure. Here are some illustrative examples:\n\nDocker E2B K8s Apple containers Modal Vercel Daytona exe.dev\n\n```bash\n#!/usr/bin/env bash\n# dispatch.sh\nset -euo pipefail\n\ncase \"$ORB_OPERATION\" in\n\tspawn)\n\t\tdocker start \"$ORB_ID\" 2>/dev/null ||\n\t\t\tdocker run --platform linux/amd64 -d --name \"$ORB_ID\" \\\n\t\t\t\t\"$ORB_IMAGE\" sleep infinity\n\t\tdocker exec -d --env ORB_TOKEN \"$ORB_ID\" amp orb bootstrap\n\t\t;;\n\tpause)\n\t\tdocker stop \"$ORB_ID\"\n\t\t;;\n\tdelete)\n\t\tdocker rm -f \"$ORB_ID\"\n\t\t;;\nesac\n```\n\nInstall the E2B CLI and the `e2b` package, set `E2B_API_KEY`, and build a template:\n\n```bash\necho 'FROM us-central1-docker.pkg.dev/amp-prod-0/amp-orb/amp-orb:latest' \\\n > e2b.Dockerfile\ne2b template create amp-orbs --dockerfile e2b.Dockerfile \\\n --cpu-count 4 --memory-mb 8192 --ready-cmd true\nexport E2B_TEMPLATE=amp-orbs\n```\n\n```javascript\n#!/usr/bin/env node\n// dispatch.mjs\nimport { Sandbox } from 'e2b'\n\nconst {\n\tORB_OPERATION, ORB_ID, ORB_TOKEN, AMP_URL, E2B_TEMPLATE,\n} = process.env\nconst metadata = { orbId: ORB_ID }\nconst [existing] = await Sandbox.list({\n\tquery: { metadata, state: ['running', 'paused'] },\n}).nextItems()\n\nif (ORB_OPERATION === 'spawn') {\n\tconst timeoutMs = 60 * 60 * 1000\n\tconst sandbox = existing\n\t\t? await Sandbox.connect(existing.sandboxId, { timeoutMs })\n\t\t: await Sandbox.create(E2B_TEMPLATE, {\n\t\t\tmetadata, timeoutMs, lifecycle: { onTimeout: 'pause' },\n\t\t})\n\tconst envs = { ORB_TOKEN }\n\tif (AMP_URL) envs.AMP_URL = AMP_URL\n\tconst bootstrap = await sandbox.commands.run('amp orb bootstrap', {\n\t\tuser: 'user', envs, background: true, timeoutMs: 0,\n\t})\n\tawait bootstrap.disconnect()\n} else if (ORB_OPERATION === 'pause' && existing) {\n\tawait Sandbox.pause(existing.sandboxId)\n} else if (ORB_OPERATION === 'delete' && existing) {\n\tawait Sandbox.kill(existing.sandboxId)\n}\n```\n\n```bash\n#!/usr/bin/env bash\n# dispatch.sh\nset -euo pipefail\nexport PATH=\"/usr/local/bin:/opt/homebrew/bin:$PATH\"\n\n# \"$ORB_IMAGE\" is the Amp orb image.\n\nids=$(container list --all --quiet)\nexists() { grep -Fxq \"$ORB_ID\" <<<\"$ids\"; }\n\ncase \"$ORB_OPERATION\" in\n\tspawn)\n\t\tif exists; then\n\t\t\tcontainer start \"$ORB_ID\"\n\t\telse\n\t\t\tcontainer run --detach --init --rosetta \\\n\t\t\t\t--platform linux/amd64 --cpus 4 --memory 8G \\\n\t\t\t\t--name \"$ORB_ID\" \"$ORB_IMAGE\" sleep infinity\n\t\tfi\n\t\t# A bare --env NAME copies the value from the host.\n\t\tcontainer exec --detach --env ORB_TOKEN --env AMP_URL \\\n\t\t\t\"$ORB_ID\" amp orb bootstrap\n\t\t;;\n\tpause)\n\t\tif exists; then\n\t\t\tcontainer stop \"$ORB_ID\"\n\t\tfi\n\t\t;;\n\tdelete)\n\t\tif exists; then\n\t\t\tcontainer delete --force \"$ORB_ID\"\n\t\tfi\n\t\t;;\n\t*)\n\t\texit 1\n\t\t;;\nesac\n```\n\n```python\n#!/usr/bin/env python3\n# dispatch.py\nimport os\n\nimport modal\n\n# Needs `pip install modal` plus MODAL_TOKEN_ID and MODAL_TOKEN_SECRET.\nAPP = \"amp-orbs\"\napp = modal.App.lookup(APP, create_if_missing=True)\nsnapshots = modal.Dict.from_name(\"amp-orb-snapshots\", create_if_missing=True)\norb_id = os.environ[\"ORB_ID\"]\n\ntry:\n sandbox = modal.Sandbox.from_name(APP, orb_id)\nexcept modal.exception.NotFoundError:\n sandbox = None\n\nmatch os.environ[\"ORB_OPERATION\"]:\n case \"spawn\":\n if sandbox is None:\n # Modal has no pause, so resume from the last snapshot.\n snapshot = snapshots.get(orb_id)\n if snapshot:\n image = modal.Image.from_id(snapshot)\n else:\n image = modal.Image.from_registry(os.environ[\"ORB_IMAGE\"])\n sandbox = modal.Sandbox.create(\n \"sleep\", \"infinity\", app=app, name=orb_id, image=image,\n cpu=4, memory=(16384, 16384), timeout=24 * 60 * 60,\n )\n # Modal execs run as root; point bootstrap at the image user's home.\n bootstrap = \"setsid amp orb bootstrap /dev/null 2>&1 &\"\n sandbox.exec(\n \"bash\", \"-c\", bootstrap,\n env={\n \"ORB_TOKEN\": os.environ[\"ORB_TOKEN\"],\n \"AMP_URL\": os.environ.get(\"AMP_URL\"),\n \"HOME\": \"/home/user\", \"USER\": \"user\",\n },\n ).wait()\n case \"pause\":\n if sandbox:\n image_id = sandbox.snapshot_filesystem(timeout=120).object_id\n snapshots[orb_id] = image_id\n sandbox.terminate()\n case \"delete\":\n if sandbox:\n sandbox.terminate()\n snapshots.pop(orb_id, None)\n```\n\n```javascript\n#!/usr/bin/env node\n// dispatch.mjs\nimport { APIError, Sandbox, Snapshot } from '@vercel/sandbox'\n\nconst { ORB_OPERATION, ORB_ID, ORB_IMAGE, ORB_TOKEN, AMP_URL } = process.env\nconst credentials = {\n\ttoken: process.env.VERCEL_TOKEN,\n\tteamId: process.env.VERCEL_TEAM_ID,\n\tprojectId: process.env.VERCEL_PROJECT_ID,\n}\n\nif (ORB_OPERATION === 'spawn') {\n\tconst sandbox = await Sandbox.getOrCreate({\n\t\t...credentials,\n\t\tname: ORB_ID,\n\t\t// Copy Amp's image to VCR, then set ORB_IMAGE to its VCR URL.\n\t\timage: ORB_IMAGE,\n\t\tresources: { vcpus: 4 },\n\t\ttimeout: 60 * 60 * 1000,\n\t\tpersistent: true,\n\t\tsnapshotExpiration: 0,\n\t\tkeepLastSnapshots: { count: 1, expiration: 0, deleteEvicted: true },\n\t})\n\tconst setup = await sandbox.runCommand({\n\t\tcmd: '/bin/bash',\n\t\targs: ['-c', 'hostname localhost && mkdir -p /vercel/sandbox'],\n\t\tsudo: true,\n\t})\n\tif (setup.exitCode !== 0) throw new Error(await setup.stderr())\n\tawait sandbox.runCommand({\n\t\tcmd: '/usr/bin/setpriv',\n\t\targs: [\n\t\t\t'--reuid=user', '--regid=user', '--init-groups', '--',\n\t\t\t'/usr/bin/env', `ORB_TOKEN=${ORB_TOKEN}`,\n\t\t\t...(AMP_URL ? [`AMP_URL=${AMP_URL}`] : []),\n\t\t\t'HOME=/home/user', 'USER=user', '/bin/bash', '-lc',\n\t\t\t'exec amp orb bootstrap',\n\t\t],\n\t\tsudo: true,\n\t\tdetached: true,\n\t})\n} else if (ORB_OPERATION === 'pause' || ORB_OPERATION === 'delete') {\n\ttry {\n\t\tconst sandbox = await Sandbox.get({\n\t\t\t...credentials, name: ORB_ID, resume: false,\n\t\t})\n\t\tif (ORB_OPERATION === 'delete') {\n\t\t\tif (sandbox.status === 'running') await sandbox.stop()\n\t\t\tfor await (const saved of await sandbox.listSnapshots()) {\n\t\t\t\tif (saved.status !== 'created') continue\n\t\t\t\tconst snapshot = await Snapshot.get({\n\t\t\t\t\t...credentials, snapshotId: saved.id,\n\t\t\t\t})\n\t\t\t\tawait snapshot.delete()\n\t\t\t}\n\t\t\tawait sandbox.delete()\n\t\t} else if (sandbox.status === 'running') await sandbox.stop()\n\t} catch (error) {\n\t\tif (!(error instanceof APIError && error.response.status === 404)) {\n\t\t\tthrow error\n\t\t}\n\t}\n}\n```\n\n```python\n#!/usr/bin/env python3\n# dispatch.py\nimport os\nfrom uuid import uuid4\nfrom daytona import (\n Daytona, DaytonaNotFoundError, CreateSandboxFromImageParams,\n Resources, SessionExecuteRequest, SandboxState,\n)\n\ndaytona = Daytona()\noperation = os.environ['ORB_OPERATION']\ntry:\n sandbox = daytona.get(os.environ['ORB_ID'])\nexcept DaytonaNotFoundError:\n sandbox = None\n\nif operation == 'spawn':\n if sandbox is None:\n sandbox = daytona.create(CreateSandboxFromImageParams(\n name=os.environ['ORB_ID'], image=os.environ['ORB_IMAGE'],\n os_user='user', resources=Resources(cpu=4, memory=8, disk=10),\n auto_stop_interval=0, auto_delete_interval=-1,\n ), timeout=240)\n elif sandbox.state != SandboxState.STARTED:\n sandbox.start()\n env = {key: os.environ[key] for key in ('ORB_TOKEN', 'AMP_URL')\n if key in os.environ}\n sandbox.update_env(env, unset=['AMP_URL'])\n session = str(uuid4())\n sandbox.process.create_session(session)\n sandbox.process.execute_session_command(session, SessionExecuteRequest(\n command=\"bash -lc 'exec amp orb bootstrap'\", run_async=True,\n ))\nelif operation == 'pause' and sandbox:\n if sandbox.state == SandboxState.STARTED:\n sandbox.stop()\nelif operation == 'delete' and sandbox:\n sandbox.delete()\n```\n\n```bash\n#!/usr/bin/env bash\n# dispatch.sh\nset -euo pipefail\n\n# Pause/resume currently requires access enabled by exe.dev support.\nstatus=$(ssh exe.dev ls \"$ORB_ID\" --json |\n jq -r --arg id \"$ORB_ID\" '.vms[] | select(.vm_name == $id) | .status')\n\ncase \"$ORB_OPERATION\" in\n spawn)\n if [[ -z \"$status\" ]]; then\n ssh exe.dev new --name=\"$ORB_ID\" --image=\"$ORB_IMAGE\" \\\n --cpu=2 --memory=8G --no-email\n elif [[ \"$status\" == paused ]]; then\n ssh exe.dev resume \"$ORB_ID\"\n fi\n {\n printf 'export ORB_TOKEN=%q\\n' \"$ORB_TOKEN\"\n if [[ -n \"${AMP_URL:-}\" ]]; then\n printf 'export AMP_URL=%q\\n' \"$AMP_URL\"\n fi\n cat <<'BOOTSTRAP'\nsudo -u user --preserve-env=ORB_TOKEN,AMP_URL bash -lc \\\n 'cd \"$HOME\"; nohup amp orb bootstrap .amp-bootstrap.log 2>&1 &'\nBOOTSTRAP\n } | ssh \"$ORB_ID.exe.xyz\" bash -s\n ;;\n pause)\n if [[ \"$status\" == running ]]; then\n ssh exe.dev pause \"$ORB_ID\"\n fi\n ;;\n delete)\n if [[ -n \"$status\" ]]; then\n ssh exe.dev rm \"$ORB_ID\"\n fi\n ;;\nesac\n```\n\nUse [Amp's Helm chart](https://ampcode.com/docs/orbs/self-hosted/kubernetes#install) to run orbs on **GKE, EKS, or AKS**. Under the hood, it runs `amp orb provider` with a supplied dispatch program that handles spawning, pausing, and deleting orbs. You don't need to write a dispatch script yourself.\n\n1. [Create a custom orb provider](https://ampcode.com/docs/orbs/self-hosted#set-up-a-provider) in your Amp workspace and copy its token.\n2. Prepare a dedicated cluster with [worker nodes and snapshot storage](https://ampcode.com/docs/orbs/self-hosted/kubernetes#supported-platforms). Paused orbs are saved to storage and can resume on another worker node.\n3. [Download the Kubernetes setup files](https://ampcode.com/docs/orbs/self-hosted/bundle.zip). The ZIP includes `gke.md`, `eks.md`, and `aks.md` with the setup and Helm commands for each cloud, plus Terraform examples. Use the instructions for your cloud to install the chart and test your first orb.\n\nThese examples use Amp's pre-built `ORB_IMAGE`, which includes the Amp CLI and other dependencies. You can use a different Linux image as long as you can start `amp orb bootstrap` in it (and [it has the dependencies for other features](https://ampcode.com/docs/orbs/self-hosted#bring-your-own-image)). That process connects the orb to Amp so Amp can set up the environment and run the agent's tools.\n\nOnce you have your dispatch program, go to your workspace settings (individuals can create a workspace for free), add a [**Custom Orb Provider**](https://ampcode.com/workspace#custom-orb-providers), copy the token, and run `amp orb provider`:\n\n```shell-session\n$ chmod +x dispatch.sh\n$ export AMP_ORB_PROVIDER_TOKEN=\"\"\n$ amp orb provider ./dispatch.sh\n```\n\nOnce that runs, open ampcode.com or the Amp macOS or iOS applications and create a new thread. Expand **Orb** and choose your provider under **Self-Hosted**.\n\n![The full new thread composer with the executor picker open and our-k8s-orbs highlighted and selected under Self-Hosted](https://static.ampcode.com/news/self-hosted-orbs-editor-light.avif) ![The full new thread composer with the executor picker open and our-k8s-orbs highlighted and selected under Self-Hosted](https://static.ampcode.com/news/self-hosted-orbs-editor-dark.avif)\n\nAnd then submit your prompt. Amp will send a request to your provider to spawn an orb, clone your repository, run your setup files, and start the agent.\n\nAnd thus begins, as they say, orbin' time. Self-hosted.\n\n## You Probably Shouldn't Self-Host Orbs\n\nAll that said: you probably shouldn't self-host orbs.\n\nWe built self-hosted orbs for enterprises that can't use the orbs we host, because regulations might restrict where their code runs, because they need access to internal networks, or because they need custom hardware attached.\n\nIf you're on an Enterprise plan, let us know and we'll help you set it up.\n\nThat's why the interface is so open: we want to support all the infrastructure our enterprise customers might have, as long as it meets the qualitative requirements above (fast-to-start, resumable machines that scale to zero, etc.). But that also means we only support our end of the contract, not every possible piece of infrastructure you can plug in.\n\n## Pricing\n\nSelf-hosted orbs are free for individuals and teams. Enterprises will be charged [standard orb pricing](https://ampcode.com/docs/orbs/sizes-and-costs) starting October 29. Until then, self-hosted orbs are free for every workspace.\n\n## Getting Started\n\nFor more information on self-hosted orbs and how to run self-hosted orbs on Kubernetes, [see the documentation](https://ampcode.com/docs/orbs/self-hosted).\n", "dateCreated": "2026-10-22T17:33:41.202070908+00:00", "date_created": "2026-10-22T00:00:00+00:00", "date_modified": "2026-10-22T00:00:00+00:00", "date_published": "2026-10-22T00:00:00+00:00", "description": "You can now self-host orbs. You provide the compute and Amp turns it into orbs. If you have compute that can quickly start new machines put them to sleep and resume them equally fast keep them around for a long time scale them to zero, so…", "external_url": "https://ampcode.com/news/self-hosted-orbs", "git": { "commit": "20068632b65d2830a2d54f25ca1d90d697bea2c0", "path": "items/ampcode-com/2026/10/2026-10-22-self-hosted-orbs.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/20068632b65d2830a2d54f25ca1d90d697bea2c0/items/ampcode-com/2026/10/2026-10-22-self-hosted-orbs.md" }, "id": "urn:aggr:item:9b916e3e65ab070d3909aa590e0d55f63dd6d7ba", "isBasedOn": { "@id": "https://ampcode.com/news/self-hosted-orbs" }, "mainEntity": { "@id": "https://ampcode.com/news/self-hosted-orbs", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/ampcode-com/2026-10-22-self-hosted-orbs/#webpage" }, "dateModified": "2026-10-22T00:00:00+00:00", "datePublished": "2026-10-22T00:00:00+00:00", "headline": "Self-Hosted Orbs", "image": { "@type": "ImageObject", "caption": null, "height": 90, "url": "https://ampcode.com/og?_template=news&_version=7&title=Self-Hosted+Orbs&date=October+22%2C+2026&tagline=Run+orbs+on+your+own+infrastructure+with+your+security+policies%2C+internal+tools%2C+and+private+services.&sig=ebcfffe1f19abf1d6dd4eed6cf0881f404d489f34a1b7067237eb14578b5bb2e", "width": 160 }, "timeRequired": "PT7M", "url": "https://ampcode.com/news/self-hosted-orbs", "wordCount": 1518 }, "name": "Archived snapshot: Self-Hosted Orbs", "preview": { "alt": null, "color": null, "height": 90, "placeholder": { "data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=", "hash": "" }, "url": "https://ampcode.com/og?_template=news&_version=7&title=Self-Hosted+Orbs&date=October+22%2C+2026&tagline=Run+orbs+on+your+own+infrastructure+with+your+security+policies%2C+internal+tools%2C+and+private+services.&sig=ebcfffe1f19abf1d6dd4eed6cf0881f404d489f34a1b7067237eb14578b5bb2e", "width": 160 }, "reading_minutes": 7, "replicated_at": null, "source": "ampcode-com", "source_name": "Amp News", "summary": "You can now self-host orbs. You provide the compute and Amp turns it into orbs. If you have compute that can quickly start new machines put them to sleep and resume them equally fast keep them around for a long time scale them to zero, so no one has to worry about having a lot of them sleeping then you are now able to replicate the orb experience within your own infrastructure. How It Works You run amp orb provider inside your infrastructure. The orb provider then reaches out to Amp and waits for requests to spawn, pause, or delete orbs. Like this: How you satisfy those requests is up to you, because amp orb provider will dispatch the requests for orb operations (spawn to create or resume orbs, pause, and delete) to a program that you provide, like so: $ amp orb provider ./dispatch.sh In that program, you can do whatever works best for your infrastructure. Here are some illustrative examples: Docker E2B K8s Apple containers Modal Vercel Daytona exe.dev #!/usr/bin/env bash # dispatch.sh set -euo pipefail case \"$ORB_OPERATION\" in spawn) docker start \"$ORB_ID\" 2>/dev/null || docker run --platform linux/amd64 -d --name \"$ORB_ID\" \\ \"$ORB_IMAGE\" sleep infinity docker exec -d --env ORB_TOKEN \"$ORB_ID\" amp orb bootstrap ;; pause) docker stop \"$ORB_ID\" ;; delete) docker rm -f \"$ORB_ID\" ;; esac Install the E2B CLI and the e2b package, set E2B_API_KEY, and build a template: echo 'FROM us-central1-docker.pkg.dev/amp-prod-0/amp-orb/amp-orb:latest' \\ > e2b.Dockerfile e2b template create amp-orbs --dockerfile e2b.Dockerfile \\ --cpu-count 4 --memory-mb 8192 --ready-cmd true export E2B_TEMPLATE=amp-orbs #!/usr/bin/env node // dispatch.mjs import { Sandbox } from 'e2b' const { ORB_OPERATION, ORB_ID, ORB_TOKEN, AMP_URL, E2B_TEMPLATE, } = process.env const metadata = { orbId: ORB_ID } const [existing] = await Sandbox.list({ query: { metadata, state: ['running', 'paused'] }, }).nextItems() if (ORB_OPERATION === 'spawn') { const timeoutMs = 60 * 60 * 1000 const sandbox = existing ? await Sandbox.connect(existing.sandboxId, { timeoutMs }) : await Sandbox.create(E2B_TEMPLATE, { metadata, timeoutMs, lifecycle: { onTimeout: 'pause' }, }) const envs = { ORB_TOKEN } if (AMP_URL) envs.AMP_URL = AMP_URL const bootstrap = await sandbox.commands.run('amp orb bootstrap', { user: 'user', envs, background: true, timeoutMs: 0, }) await bootstrap.disconnect() } else if (ORB_OPERATION === 'pause' && existing) { await Sandbox.pause(existing.sandboxId) } else if (ORB_OPERATION === 'delete' && existing) { await Sandbox.kill(existing.sandboxId) } #!/usr/bin/env bash # dispatch.sh set -euo pipefail export PATH=\"/usr/local/bin:/opt/homebrew/bin:$PATH\" # \"$ORB_IMAGE\" is the Amp orb image. ids=$(container list --all --quiet) exists() { grep -Fxq \"$ORB_ID\" <<<\"$ids\"; } case \"$ORB_OPERATION\" in spawn) if exists; then container start \"$ORB_ID\" else container run --detach --init --rosetta \\ --platform linux/amd64 --cpus 4 --memory 8G \\ --name \"$ORB_ID\" \"$ORB_IMAGE\" sleep infinity fi # A bare --env NAME copies the value from the host. container exec --detach --env ORB_TOKEN --env AMP_URL \\ \"$ORB_ID\" amp orb bootstrap ;; pause) if exists; then container stop \"$ORB_ID\" fi ;; delete) if exists; then container delete --force \"$ORB_ID\" fi ;; *) exit 1 ;; esac #!/usr/bin/env python3 # dispatch.py import os import modal # Needs `pip install modal` plus MODAL_TOKEN_ID and MODAL_TOKEN_SECRET. APP = \"amp-orbs\" app = modal.App.lookup(APP, create_if_missing=True) snapshots = modal.Dict.from_name(\"amp-orb-snapshots\", create_if_missing=True) orb_id = os.environ[\"ORB_ID\"] try: sandbox = modal.Sandbox.from_name(APP, orb_id) except modal.exception.NotFoundError: sandbox = None match os.environ[\"ORB_OPERATION\"]: case \"spawn\": if sandbox is None: # Modal has no pause, so resume from the last snapshot. snapshot = snapshots.get(orb_id) if snapshot: image = modal.Image.from_id(snapshot) else: image = modal.Image.from_registry(os.environ[\"ORB_IMAGE\"]) sandbox = modal.Sandbox.create( \"sleep\", \"infinity\", app=app, name=orb_id, image=image, cpu=4, memory=(16384, 16384), timeout=24 * 60 * 60, ) # Modal execs run as root; point bootstrap at the image user's home. bootstrap = \"setsid amp orb bootstrap /dev/null 2>&1 &\" sandbox.exec( \"bash\", \"-c\", bootstrap, env={ \"ORB_TOKEN\": os.environ[\"ORB_TOKEN\"], \"AMP_URL\": os.environ.get(\"AMP_URL\"), \"HOME\": \"/home/user\", \"USER\": \"user\", }, ).wait() case \"pause\": if sandbox: image_id = sandbox.snapshot_filesystem(timeout=120).object_id snapshots[orb_id] = image_id sandbox.terminate() case \"delete\": if sandbox: sandbox.terminate() snapshots.pop(orb_id, None) #!/usr/bin/env node // dispatch.mjs import { APIError, Sandbox, Snapshot } from '@vercel/sandbox' const { ORB_OPERATION, ORB_ID, ORB_IMAGE, ORB_TOKEN, AMP_URL } = process.env const credentials = { token: process.env.VERCEL_TOKEN, teamId: process.env.VERCEL_TEAM_ID, projectId: process.env.VERCEL_PROJECT_ID, } if (ORB_OPERATION === 'spawn') { const sandbox = await Sandbox.getOrCreate({ ...credentials, name: ORB_ID, // Copy Amp's image to VCR, then set ORB_IMAGE to its VCR URL. image: ORB_IMAGE, resources: { vcpus: 4 }, timeout: 60 * 60 * 1000, persistent: true, snapshotExpiration: 0, keepLastSnapshots: { count: 1, expiration: 0, deleteEvicted: true }, }) const setup = await sandbox.runCommand({ cmd: '/bin/bash', args: ['-c', 'hostname localhost && mkdir -p /vercel/sandbox'], sudo: true, }) if (setup.exitCode !== 0) throw new Error(await setup.stderr()) await sandbox.runCommand({ cmd: '/usr/bin/setpriv', args: [ '--reuid=user', '--regid=user', '--init-groups', '--', '/usr/bin/env', `ORB_TOKEN=${ORB_TOKEN}`, ...(AMP_URL ? [`AMP_URL=${AMP_URL}`] : []), 'HOME=/home/user', 'USER=user', '/bin/bash', '-lc', 'exec amp orb bootstrap', ], sudo: true, detached: true, }) } else if (ORB_OPERATION === 'pause' || ORB_OPERATION === 'delete') { try { const sandbox = await Sandbox.get({ ...credentials, name: ORB_ID, resume: false, }) if (ORB_OPERATION === 'delete') { if (sandbox.status === 'running') await sandbox.stop() for await (const saved of await sandbox.listSnapshots()) { if (saved.status !== 'created') continue const snapshot = await Snapshot.get({ ...credentials, snapshotId: saved.id, }) await snapshot.delete() } await sandbox.delete() } else if (sandbox.status === 'running') await sandbox.stop() } catch (error) { if (!(error instanceof APIError && error.response.status === 404)) { throw error } } } #!/usr/bin/env python3 # dispatch.py import os from uuid import uuid4 from daytona import ( Daytona, DaytonaNotFoundError, CreateSandboxFromImageParams, Resources, SessionExecuteRequest, SandboxState, ) daytona = Daytona() operation = os.environ['ORB_OPERATION'] try: sandbox = daytona.get(os.environ['ORB_ID']) except DaytonaNotFoundError: sandbox = None if operation == 'spawn': if sandbox is None: sandbox = daytona.create(CreateSandboxFromImageParams( name=os.environ['ORB_ID'], image=os.environ['ORB_IMAGE'], os_user='user', resources=Resources(cpu=4, memory=8, disk=10), auto_stop_interval=0, auto_delete_interval=-1, ), timeout=240) elif sandbox.state != SandboxState.STARTED: sandbox.start() env = {key: os.environ[key] for key in ('ORB_TOKEN', 'AMP_URL') if key in os.environ} sandbox.update_env(env, unset=['AMP_URL']) session = str(uuid4()) sandbox.process.create_session(session) sandbox.process.execute_session_command(session, SessionExecuteRequest( command=\"bash -lc 'exec amp orb bootstrap'\", run_async=True, )) elif operation == 'pause' and sandbox: if sandbox.state == SandboxState.STARTED: sandbox.stop() elif operation == 'delete' and sandbox: sandbox.delete() #!/usr/bin/env bash # dispatch.sh set -euo pipefail # Pause/resume currently requires access enabled by exe.dev support. status=$(ssh exe.dev ls \"$ORB_ID\" --json | jq -r --arg id \"$ORB_ID\" '.vms[] | select(.vm_name == $id) | .status') case \"$ORB_OPERATION\" in spawn) if [[ -z \"$status\" ]]; then ssh exe.dev new --name=\"$ORB_ID\" --image=\"$ORB_IMAGE\" \\ --cpu=2 --memory=8G --no-email elif [[ \"$status\" == paused ]]; then ssh exe.dev resume \"$ORB_ID\" fi { printf 'export ORB_TOKEN=%q\\n' \"$ORB_TOKEN\" if [[ -n \"${AMP_URL:-}\" ]]; then printf 'export AMP_URL=%q\\n' \"$AMP_URL\" fi cat <<'BOOTSTRAP' sudo -u user --preserve-env=ORB_TOKEN,AMP_URL bash -lc \\ 'cd \"$HOME\"; nohup amp orb bootstrap .amp-bootstrap.log 2>&1 &' BOOTSTRAP } | ssh \"$ORB_ID.exe.xyz\" bash -s ;; pause) if [[ \"$status\" == running ]]; then ssh exe.dev pause \"$ORB_ID\" fi ;; delete) if [[ -n \"$status\" ]]; then ssh exe.dev rm \"$ORB_ID\" fi ;; esac Use Amp's Helm chart to run orbs on GKE, EKS, or AKS. Under the hood, it runs amp orb provider with a supplied dispatch program that handles spawning, pausing, and deleting orbs. You don't need to write a dispatch script yourself. Create a custom orb provider in your Amp workspace and copy its token. Prepare a dedicated cluster with worker nodes and snapshot storage. Paused orbs are saved to storage and can resume on another worker node. Download the Kubernetes setup files. The ZIP includes gke.md, eks.md, and aks.md with the setup and Helm commands for each cloud, plus Terraform examples. Use the instructions for your cloud to install the chart and test your first orb. These examples use Amp's pre-built ORB_IMAGE, which includes the Amp CLI and other dependencies. You can use a different Linux image as long as you can start amp orb bootstrap in it (and it has the dependencies for other features). That process connects the orb to Amp so Amp can set up the environment and run the agent's tools. Once you have your dispatch program, go to your workspace settings (individuals can create a workspace for free), add a Custom Orb Provider, copy the token, and run amp orb provider: $ chmod +x dispatch.sh $ export AMP_ORB_PROVIDER_TOKEN=\"\" $ amp orb provider ./dispatch.sh Once that runs, open ampcode.com or the Amp macOS or iOS applications and create a new thread. Expand Orb and choose your provider under Self-Hosted. And then submit your prompt. Amp will send a request to your provider to spawn an orb, clone your repository, run your setup files, and start the agent. And thus begins, as they say, orbin' time. Self-hosted. You Probably Shouldn't Self-Host Orbs All that said: you probably shouldn't self-host orbs. We built self-hosted orbs for enterprises that can't use the orbs we host, because regulations might restrict where their code runs, because they need access to internal networks, or because they need custom hardware attached. If you're on an Enterprise plan, let us know and we'll help you set it up. That's why the interface is so open: we want to support all the infrastructure our enterprise customers might have, as long as it meets the qualitative requirements above (fast-to-start, resumable machines that scale to zero, etc.). But that also means we only support our end of the contract, not every possible piece of infrastructure you can plug in. Pricing Self-hosted orbs are free for individuals and teams. Enterprises will be charged standard orb pricing starting October 29. Until then, self-hosted orbs are free for every workspace. Getting Started For more information on self-hosted orbs and how to run self-hosted orbs on Kubernetes, see the documentation.", "tags": [], "temporalCoverage": "2026-10-22T17:33:41.202070908+00:00", "title": "Self-Hosted Orbs", "url": "https://aggr.aymericbeaumet.com/items/ampcode-com/2026-10-22-self-hosted-orbs/", "word_count": 1518 }