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 + next to Local Folders and choose the folders threads started on any device can run in. Any folder works:

    • Add Folder… adds one project. A thread starts in the exact folder you pick, so choose the project’s Git checkout, not a folder that holds several.
    • Add Parent Folder… adds a folder that holds your projects, such as ~/code.
    • Add Home Folder lets threads start in ~ and work anywhere in your home folder, but it does not add the projects inside it to the picker.

    Choose Projects…, when your account has it, lists the Git projects on your Mac so you can tick the ones threads can run in.

Every local folder is listed under Local Folders. To remove one, click its ⋯ button and choose Remove Folder.

Parent Folders

A parent folder shares every Git project inside it, up to two levels deep, including Git worktrees and clones you create later. It shows as one row with the number of projects found, such as ~/code · 12 Git projects. To stop sharing one of those projects, move it out of the parent folder or remove the parent folder. Adding or removing a parent folder restarts the runner.

A parent folder is the app’s form of the CLI’s --discover-dirs.

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, with one --discover-dirs=<folder> per parent folder. It serves only the folders you add and the checkouts it finds in those folders. 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 the PATH of your interactive login shell (the same one Terminal gives you, including anything ~/.zshrc adds), 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. In the Runner tab, Copy Terminal Command in the + menu copies the 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.

Open Files in Your Editor

In a thread that runs on this Mac, a text file open in the file viewer has Open in Editor in its ⋮ menu. It opens the file in the app macOS uses for that kind of file when that app edits code, and otherwise in your default app for source code. To pick the editor, select a file of that type in Finder, choose Get Info, and change Open with.

Show Files in Finder

In a thread that runs on this Mac, Show in Finder opens a Finder window with the file or folder selected, so you can drag it into another app, such as a Slack message, without downloading a copy. It is in the menu of every file and folder in the Files tab, and in the ⋮ menu of a file open in the file viewer.

Allow Terminal Access

A thread’s Terminal tab opens a shell on the runner only when the runner was started with --remote-control-terminal, so on the app’s runner it says that terminal access is disabled by default. Turn on Allow Terminal Access in the Runner tab to start the runner with that flag; the app restarts the runner, then reload the thread page.

The switch applies only to threads that run on the app’s runner. A thread you started with amp in a terminal runs in that amp session, not on the runner, so restart that session with --remote-control-terminal instead (see Terminal Access).

Allow Portals

Turn on Allow Portals in the Runner tab to start the runner with --remote-control-portals, so threads running on this Mac can share the web servers they start as portals. It is off by default, and the app restarts the runner when you change it.

Share This Mac’s Display

Turn on Share This Mac’s Display in the Runner tab to see and control this Mac from the Desktop tab of any thread running on it, in a browser or on your phone. macOS then asks you to allow Screen Recording and Accessibility for Amp Desktop Helper; the Runner tab shows both grants and can ask again.

Anyone who can write to a thread running on this Mac can see and control its display. It needs an Apple Silicon Mac. Read See and Control the Runner’s Desktop for more.

Share With Your Workspace

Turn on Share With Workspace in the Runner tab to share the app’s runner with your workspace, as --share does in Terminal. Workspace members can then start threads on this Mac, and so can Spaces, whose threads are shared with the workspace and run only on orbs and shared runners. Before it turns on, the app asks you to confirm, because those threads run any code as you, with access to your files, credentials, and sign-ins. Turn it off to stop sharing; the app restarts the runner without --share.

The switch shows only when your workspace allows sharing runners. If it is missing, update the app, then ask a workspace admin to turn on Allow Members to Share Runners under Member Settings in the workspace settings.

Share Your Network

The Runner tab shows Share This Mac’s Network Connection. Turn it on, then route an orb through this Mac.

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 off by default. Turn on Keep This Mac Awake in the Runner tab or in the menu bar menu to keep the Mac awake while it is a runner.

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.