Self-host Amp orbs

Before you start#

• An Amp account. Any plan works; self-hosted orbs are free except on Enterprise.
• For private repositories, GitHub connected in Amp's integration settings. Amp clones and pushes from the orb with short-lived tokens of that connection, so no GitHub credentials go on your VMs.
• A provider and its token. In your personal Settings → Orbs, click Add Provider and name it exe-dev (you pick it by this name later). Copy the aop_live_… token: Amp shows it only once. In a workspace, an admin can add one under the workspace's Settings → Orbs instead, and every member can use it.

Set up the provider#

Deploy sets it up on a new VM and asks for the provider token. To do it yourself:

ssh exe.dev new --name=my-amp
ssh my-amp.exe.xyz

curl -fsSL https://ampcode.com/install.sh | bash
mkdir -p ~/amp-orbs && cd ~/amp-orbs
curl -fsSLO https://exe.dev/deploy/amp/dispatch.sh
chmod +x dispatch.sh
~/.local/bin/amp --version

(umask 077; read -rsp 'Provider token: ' t && printf 'AMP_ORB_PROVIDER_TOKEN=%s\n' "$t" > ~/amp-orbs/provider.env); echo
ls -l ~/amp-orbs/provider.env

sudo tee /etc/systemd/system/amp-orb-provider.service >/dev/null <<'EOF'
[Unit]
Description=Amp orb provider (self-hosted orbs on exe.dev VMs)
Wants=network-online.target
After=network-online.target

[Service]
User=exedev
WorkingDirectory=/home/exedev/amp-orbs
EnvironmentFile=/home/exedev/amp-orbs/provider.env
ExecStart=/home/exedev/.local/bin/amp orb provider /home/exedev/amp-orbs/dispatch.sh
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now amp-orb-provider
sleep 10; systemctl is-active amp-orb-provider
journalctl -u amp-orb-provider --no-pager -n 20

Let the provider make VMs#

The provider VM makes orb VMs through exe.dev's API, by way of an integration that holds the key, so no key is on any VM. On your computer:

ssh exe.dev integrations add exe-dev --name amp-orbs \
  --tag amp-orb --cmds ls,new,ssh,rm,pause,resume --attach vm:my-amp

The integration can list, make, reach, pause and delete VMs tagged amp-orb, and nothing else; the VMs it makes get that tag. Only the provider VM can use it, and ssh exe.dev integrations remove amp-orbs revokes it. On the provider VM, check it:

curl -s -X POST https://amp-orbs.int.exe.xyz/exec -d ls

Expect {"vms":[]}.

Start a thread on your VMs#

On ampcode.com or in the Amp app, click New Thread, then Orb, open the type dropdown and choose exe-dev under Self-Hosted (marked Personal). Pick a project, or No Project for a clean orb, and give it a task:

Build a tiny website for a sandwich critic with strong opinions, serve it, and show me a screenshot.

From a terminal, the same thing is:

amp -ox "Run the tests and fix any failures" --orb-provider exe-dev

It prints the thread's URL and returns; the agent keeps going. Amp sends the provider a spawn job. The first orb takes about 40 seconds while exe.dev pulls Amp's image; in our tests every orb after that was up and connected about 3 seconds after Amp sent the job. Amp then clones the repository, runs the project's .agents/setup and starts the agent. The provider's log, and the thread's setup log, show dispatch.sh's lines:

info Claimed job {"jobId":"spawn:amp-01a1b6e2-…","op":"spawn",…}
created VM amp-01a1b6e2-efed-7101-8974-5f86613e3a5e
started amp orb bootstrap in amp-01a1b6e2-efed-7101-8974-5f86613e3a5e

Close your laptop: the agent keeps working on the VM. When the thread goes idle, or you archive it, Amp sends pause and dispatch.sh pauses the VM within a few seconds (paused VM amp-…). Your next message sends spawn, and the same VM is back in about 3 seconds (resumed VM amp-…). Deleting the thread deletes its VM.

exe.dev's pause saves the VM's memory as well as its disk and frees its CPU and memory, so a woken orb still has its dev servers, terminals and desktop apps running: in our test, a web server the agent started before the pause answered after it with the same process ID. (Amp's docs say pausing needs exe.dev support to turn it on; it no longer does.)

Look inside an orb#

Each orb is an exe.dev VM named after it. On your computer:

ssh exe.dev ls 'amp-*'
ssh amp-<orb id>.exe.xyz

You're root there; the agent works as user, in /home/user/workspace. The thread's Terminal, Portals and Desktop tabs reach the orb through Amp's tunnel, as on Amp-hosted orbs. Anything an orb serves on a port from 3000 to 9999 is also at https://amp-<orb id>.exe.xyz:<port>/, private to you behind exe.dev's HTTPS proxy.

• Bigger orbs: in the provider's Edit dialog in Amp, add an orb type named large. dispatch.sh gives it 4 CPUs and 16 GB; any other type gets exe.dev's default size. Pick it in the type dropdown, or with --orb-size large. Edit the case in dispatch.sh for more types.
• Your own image: set ORB_IMAGE in ~/amp-orbs/provider.env and restart the service. Amp's image requirements apply.

Or: run threads on the VM itself#

Amp's other way to use a machine you own is a runner: amp --no-tui serves the directories on one machine, and every thread you send to it runs there, with the tools and logins you set up. It suits a VM you treat as your dev box. A runner run by a service signs in with an Amp access token: create one in Amp's Settings → Security (it starts with sgamp_). It can do anything your Amp account can, so it goes in a file only you can read. On the VM, paste it at the prompt, then start the runner as a service under the VM's name:

(umask 077; read -rsp 'Amp access token: ' t && printf 'AMP_API_KEY=%s\n' "$t" > ~/amp-runner.env); echo
mkdir -p ~/code
sudo tee /etc/systemd/system/amp-runner.service >/dev/null <<'EOF'
[Unit]
Description=Amp runner
Wants=network-online.target
After=network-online.target

[Service]
User=exedev
WorkingDirectory=/home/exedev/code
EnvironmentFile=/home/exedev/amp-runner.env
ExecStart=/home/exedev/.local/bin/amp --no-tui --runner-id %H --discover-dirs
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now amp-runner
sleep 10; journalctl -u amp-runner --no-pager | grep Registered

Success is Registered as <your email>. Create threads on https://ampcode.com/ and they will run here.

Clone repositories into ~/code; the runner serves each checkout there and picks up new ones as they appear. The VM shows up under Runners when you start a thread, or from a terminal anywhere with amp -x "Run the tests" --executor runner:my-amp --runner-dir /home/exedev/code/<repo>. For private GitHub repositories, connect a GitHub repo so the VM can clone and push with no token on it. Add --remote-control-terminal to the ExecStart line for a terminal from ampcode.com. A runner updates and restarts itself when it's idle.

~/.local/bin/amp update
sudo systemctl restart amp-orb-provider

Troubleshooting#

The provider's log is journalctl -u amp-orb-provider; each job's output is there, and a spawn's output is in the thread's setup log too.

• Error: Amp rejected the orb provider token. The token is wrong or the provider was deleted. Add a new one and save it as above.
• exe.dev: integration not found or not attached to this VM. The amp-orbs integration doesn't exist or isn't attached to the provider VM. Run the integrations add command with this VM's name.
• exe.dev new amp-… failed. The JSON after it says why: often the VM limit of your plan, or an orb type bigger than your capacity.
• The thread waits for an orb, and the log shows nothing. Another provider is connected with the same token, such as a forgotten amp orb provider in a terminal; Amp sends it the jobs. Stop it.
• ORB_TOKEN was rejected by Amp in an orb's /home/user/.amp-bootstrap.log. That bootstrap was started with an old job's token, which lasts 15 minutes; send the thread another message to get a new spawn.