Runners

You can start Amp threads remotely from ampcode.com on any machine where you can run amp.

To do that, you need an Amp instance that serves as a runner.

Start a Runner

Run amp --no-tui to start a runner-only Amp instance. It waits for and runs remotely created threads in the current directory without opening the TUI.

Pass --runner-id <id> to give it a stable runner ID:

$ amp --no-tui --runner-id grandmas-garage-server

Runner IDs must be valid hostnames and are case-insensitive. Amp preserves the casing you provide.

To access the runner’s terminals from ampcode.com, pass --remote-control-terminal:

$ amp --no-tui --runner-id grandmas-garage-server --remote-control-terminal

Runners vs. Orbs

Runners can do some of what orbs can do.

FeatureRunner Support
Creating ThreadsA runner can create threads only on the machine and in the directory where it was started.
ChangesAvailable automatically when the runner directory is a Git or Jujutsu checkout. No runner flag is needed.
FilesAvailable automatically while the runner is connected. It browses the runner directory, and no runner flag is needed.
TerminalAvailable when you start the runner with --remote-control-terminal. Restart the runner with this flag, then reload the thread if it is disabled.
PortalNot supported on runners. Only orbs have portals.
DesktopNot supported on runners. Only orbs have a desktop.
MultiplayerNot supported on runners. Only non-private orb threads can be made multiplayer.

Orbs get new features first because they’re standardized and isolated environments that are easier for us to build for. Most orb features will eventually make it to runners, and you can build any particular orb features yourself for your specific needs on top of runners in the meantime.

Troubleshoot a Runner

  • If the runner does not appear in the location picker, confirm that amp --no-tui is still running and signed in to the same Amp account as the web app.
  • If Changes is unavailable, start the runner inside a Git or Jujutsu checkout.
  • If Files cannot load, confirm that the runner is connected and can still read its working directory.
  • If Terminal says access is disabled, restart the runner with --remote-control-terminal, then reload the thread page.
  • If you need Portal, create the thread in an orb. There is no runner setting that enables this view.

TUI as Runner

You can turn every interactive Amp TUI into a runner too by adding this setting:

// ~/.config/amp/settings.json

{
	"amp.remoteThreadCreation.enabled": true
}

You can also use the command amp: enable remote creation of threads to turn it on. Each TUI accepts new threads in the directory where you started it.