A machine that appears when you ask

What an orb actually is

An orb is a remote machine where an Amp agent works on its own. One thread, one orb: a fresh clone of your repository, your plugins, and the tools the agent needs.

The part that matters is where it isn't. No cores taken, no ports held, no dev server to wedge. You drive it exactly as you would on your own disk.

So orbs suit work you'd rather not host. Long builds. The suite that eats twenty minutes and all your fans. The migration you keep postponing.

Four ways to start one

amp -ox "your prompt"                       # a new execute-mode thread in an orb
amp -ox "your prompt" --orb-size a1.small   # same, at a size you pick

What's inside one

Debian 12, already equipped. The agent lands with amp and gh authenticated, agent-browser for driving a real browser, and the rest of a working machine.

Anything missing is one apt-get install away, and Amp's system prompt says so.

The lifecycle

You just watched most of this. In words:

1. Provisioning. Amp spawns the machine, clones your repository.
2. Setup. On a fresh orb, .agents/setup runs from the repo root. Amp snapshots the result and reuses it for up to 24 hours, so only the first orb of the day pays for setup.
3. Working. The agent goes, watched or not.
4. Idle. Nothing happening. A clock starts.
5. Paused. Five idle minutes and it pauses itself; archiving a thread does it too. You never do it by hand.
6. Woken. It comes back the moment it's accessed, and .agents/resume runs before the agent picks up.

The pause is the good part. Not a stopped VM you'd have to remember to restart, not a warm machine charging you for existing. It costs nothing and comes back the instant anything touches it.

What it costs

Five sizes, all with 40 GB of disk; only CPU and memory change. a1.tiny (1 CPU, 2 GB) is $0.08 an hour, a1.xxlarge (16 CPUs, 32 GB) is $1.32, and three more sizes sit between. Personal projects on Megawatt default to a1.small, and --orb-size overrides that.

Billing is by the minute, and a paused orb bills nothing. An a1.small costs under a third of a cent per minute while it works, and nothing for the rest of the day.

Extra CPUs only help work that can use them: sixteen of them are a bargain on a suite that shards and a waste on a bisect. Memory isn't a dial at all — give a job 4 GB when it needs 8 and it dies, every billed minute wasted.

Teaching your repo to wake up well

An orb is a generic Debian box with your code in it. Three committed files make it yours.

.agents/setup

Amp runs this from the repo root while preparing a fresh orb: install dependencies, generate what needs generating, check your tools are there.

#!/usr/bin/env bash
set -euo pipefail

corepack enable
pnpm install --frozen-lockfile
[ -f .env.local ] || cp -- .env.example .env.local

.agents/resume

This runs whenever a paused orb wakes, and Amp waits up to 10 seconds. Exit non-zero in that window and Amp surfaces it first; run past it and Amp stops blocking, leaving the hook to finish on its own. So keep it fast and idempotent: reconnect a tunnel, restart a watcher, nothing that installs.

#!/usr/bin/env bash
set -euo pipefail

# Fast, idempotent repair work only. Do not install dependencies here.
mkdir -p .amp
date > .amp/resume-last-ran.txt

AGENTS.md

The third file is just prose, and it compounds. The Amp repository carries 41 of them, read whenever the agent opens a file in that directory: build commands, where logs go, what to avoid. Don't make them guess.

Staying in control

The worry is always the same: I can't see what it's doing. You see more than you would locally, because the machine has a front door.

• Review from the thread. Read the changes and browse files on the orb without syncing anything down.
• Open a terminal in it. A real shell sharing the filesystem and working copy with the agent, in a tmux session it shares.
• Take it home. amp sync <thread-id> mirrors the thread's changes into your checkout while the agent carries on.

Portals

An agent that can run your app but can't show it to you is half useful. Portals are authenticated URLs onto servers inside an orb, so the dev server opens from the thread's Portal tab. Just ask for one.

Declare anything long-lived in .amp/services.yaml, and amp orb services ensure runs it supervised, so it survives the orb pausing.

services:
  web:
    command: pnpm dev
    portal:
      title: App
      description: Use the seeded test account.

Only thread viewers can reach a portal, so previews stay private without a VPN. And any request wakes a paused orb and restarts billing, so a link handed to a crawler keeps paying for a machine.

Many agents at once

Once a machine costs cents an hour and nothing while it sleeps, how many you run stops being a resource question.

Amp already splits suitable work across subagents, each with its own context and tools. They work in isolation and report back a summary: great in parallel, poor at anything needing negotiation.

What that does to your instincts:

What a day looks like

Start with the papercuts, because they're finally cheap. A misaligned button, a confusing error string, a test that's been flaky for a month. Each becomes a screenshot, a sentence and an orb.

Then the real job. Let it run long — locally that's a hostage situation, in an orb it's elapsed time on a machine you aren't using. So ask for proof, not just the diff: Ball got back a video of a Rust desktop app running in a headless orb.

Then one afternoon you close the laptop with four agents still working, which is the whole thing. A mountain of code with evidence attached is a different object from one with a confident summary. You still review it, differently.

Where this leaves you

None of this removes the hard part. What to build, which plausible answer is quietly wrong, which proof is real proof — still yours, and orbs hand you more of it, not less: five agents produce five things to judge.

What they remove is a tax you'd stopped noticing: the checkout you didn't make, the agent you cut short at minute six because you wanted your laptop back.

The entry fee is small: a setup script, a resume hook, an AGENTS.md that tells the truth about how your repository runs. Then give an orb something you've been putting off, and close the lid.

Reference

Every figure here comes from Amp's Owner's Manual and pricing page, in US dollars.

Orb sizes

Repository files that shape an orb

Plans

Commands used on this page

amp -ox "your prompt"

Start a new execute-mode thread in an orb from the CLI.

amp -ox "your prompt" --orb-size a1.small

Use a size other than the project's default for this thread.

amp sync <thread-id>

Mirror an orb thread's changes into your local checkout while the agent keeps working.

amp orb services ensure

Start every service declared in .amp/services.yaml, supervised, and write the Portal tab's links.

amp orb service restart <name>

Reload a declared service after changing its command or dependencies, keeping its port and portal settings.

amp orb portal 3000

Get the portal URL for a local port instead of hardcoding the domain format.

amp orb id-token --audience my-service

Mint a short-lived OIDC token identifying the orb's workspace, project, user and thread.

amp secrets

Manage workspace, project and personal secrets and environment variables from the CLI.