Use Your Mac as a Runner

The Amp app for macOS can start a runner for you, so you don’t need to keep amp --no-tui running in Terminal.

Turn It On

  1. Open App Settings… (⌘⇧,) and select the Runner tab.
  2. Turn on Use This Mac as a Runner.
  3. Click + and choose Add Folder…, or pick one of your projects and choose the folder it lives in. Turn on Home Folder to let threads run anywhere in your home folder.
The Runner tab in the Amp app's settings. Use This Mac as a Runner is on and Running with 3 folders and 2 threads, the runner name is hamishs-macbook-pro, Keep This Mac Awake is on, Home Folder is off, and the Folders list shows amp, sandcastle, and marketing-site. Details shows the Amp CLI version and path, with Runner Log and CLI Log links.

How It Works

The app runs amp --no-tui --no-serve-cwd --runner-id <name> in your home folder. It serves only the folders you add. It restarts the runner if it exits unexpectedly and stops it when you quit the app. The runner is named after your Mac, with an -amp-app suffix; click the pencil next to Runner Name to change it.

The app uses the Amp CLI installed on your Mac, found through your login shell’s PATH, and the CLI’s sign-in. If something is wrong with the CLI, the Runner tab says so and offers a fix:

  • Missing: Install Amp CLI opens the install page. Install the CLI, then click Retry.
  • Not signed in: Sign In… runs amp login, which signs you in through your browser. The runner starts when you finish.
  • Too old for the app: Update Amp CLI runs amp update, then starts the runner.

The folder list belongs to the runner, so you can also change it from Terminal. The Runner tab shows the exact command:

$ amp runner dirs add --runner-id macbook-pro-amp-app ~/code/amp

When you create a thread in the Mac app, runners on this Mac are marked This Mac in the executor picker. Runners you started from Terminal on the same Mac are marked too, and are listed in the Runner tab under Also Running on This Mac.

The new thread composer in the Amp app with the runner picker open. hamishs-macbook-pro is selected and marked This Mac with a MacBook icon. Below it is hamishs-dgx-spark, another runner, with no This Mac label. The new thread composer in the Amp app with the runner picker open. hamishs-macbook-pro is selected and marked This Mac with a MacBook icon. Below it is hamishs-dgx-spark, another runner, with no This Mac label.

Keep This Mac Awake

Your Mac can run threads only while it is awake. While it sleeps, you cannot start threads on it, and threads already running on it pause.

While the app’s runner is on and the Mac is plugged in, Keep This Mac Awake stops the Mac from going to sleep on its own, so you can still start threads on it after you walk away. The display can still turn off and the screen can still lock; neither stops the runner. The Amp icon in the menu bar shows a cup while the app keeps the Mac awake.

The Mac still goes to sleep, and stops running threads, when:

  • It runs on battery power, for example when you unplug a MacBook.
  • You close the lid.
  • You choose Sleep from the Apple menu.

Neither the app nor Amp can wake a sleeping Mac. It can run threads again only after you wake it yourself, for example by opening the lid or pressing a key.

The setting is on by default. Turn off Keep This Mac Awake in the Runner tab or in the menu bar menu to let the Mac sleep normally.

What Happens While Your Mac Is Asleep

  • You cannot start threads on it. Within about 90 seconds of going to sleep, the Mac disappears from the runner picker in the Mac app, on ampcode.com, and on your phone. Pick an orb or another runner instead.
  • Threads already running on it pause. Commands and file edits wait for the runner, and the thread shows that it is waiting. When you wake the Mac, the runner reconnects, usually within a minute, and the threads carry on where they stopped.