Skip to content
MacOrbMacOrb docs

Quickstart

Your Amp key and GitHub token are set up in the console. This page covers the plugin and signing in.

  1. Install the plugin

    Section titled “Install the plugin”

    Everywhere you use Amp — desktop, web and phone. In any Amp thread, say:

    Import the MacOrb plugin from github.com/rizwankce/macorb-amp into my personal plugins.

    Amp copies it into your personal plugins, so it loads in every new thread, on every device. It doesn’t update itself: to get a newer version, ask Amp to re-import it.

    This computer only. The CLI carries the same plugin and copies it into Amp’s system plugin directory, for every project on this machine:

    Terminal window
    npx @macorb/cli plugin install

    Add --project to install it into the current project’s .amp/plugins/ instead. Then start a new thread, or run amp plugins reload.

    The console cannot see your plugin directory, so it cannot confirm the install. macorb doctor can: it asks Amp itself whether the plugin loaded, and checks the token file and the API.

  2. Sign in

    Section titled “Sign in”

    Where a thread runs decides where the plugin looks for your MacOrb token.

    Desktop threads run on your computer. The CLI is the @macorb/cli package on npm and needs Node 20 or newer:

    Terminal window
    npx @macorb/cli login

    It opens the console, waits on a loopback port on this computer, and writes ~/.config/macorb/token with mode 0600 after you confirm one prompt in the browser. To keep the CLI installed, npm i -g @macorb/cli once and then type macorb on its own — macorb doctor, macorb up, macorb stop. The commands on the rest of this page are written that way.

    On a headless box, or a browser that cannot reach 127.0.0.1, copy your token and pass it directly with login --token.

    Web and phone threads run in an Amp orb, a cloud machine that has no token file. Give them a token that lives in Amp:

    1. In the console, open Settings → Amp plugin tokens and choose Create token. Copy it — MacOrb shows it once.

    2. Save it as an Amp secret named MACORB_TOKEN, at ampcode.com/settings or, with the token still copied, from a Mac terminal:

      Terminal window
      pbpaste | amp secrets set --user --secret MACORB_TOKEN --data-file -

    3. Start a new thread. Orbs read secrets when they start.

    A plugin token lasts until you revoke it in Settings. It can start and stop Macs but can’t change your account, and Sign out everywhere revokes it too.

  3. Your first task

    Section titled “Your first task”

    In an Amp thread with the plugin loaded, type:

    Build and test this on a Mac

    Amp acquires a Mac and starts a child thread on its registered runner. The command palette has the same thing as MacOrb: Run on the Mac.

    To drive a Mac from a terminal instead, start one with macorb up. Once it reports the runner registered it prints the command that attaches to it:

    Terminal window
    amp --executor runner:<runner-id>

    It attaches to a runner that is already connected, so start the Mac first.

  4. From your phone

    Section titled “From your phone”

    With the plugin in your personal plugins and MACORB_TOKEN saved in Amp, start a thread in Amp iOS and ask for a Mac exactly as on the desktop. The thread runs in an Amp orb, so your laptop can be off.

  5. Stop and save

    Section titled “Stop and save”

    Push the work you want to keep first. Then ask Amp “Stop the Mac”, run macorb stop, or stop it from the console.

What it costs

Section titled “What it costs”

A Mac is charged by the minute, from the moment it starts booting until MacOrb records it as destroyed. See Pricing for the rate and the credit packs, and the console’s Sessions page for what you have actually spent.