Orbs — a playable field guide to Amp's remote machines

01

What is an orb, exactly?

An orb is an ephemeral remote machine where an Amp agent runs without supervision. When you create a new thread, Amp doesn’t just start a chat — it provisions a whole fresh computer for the conversation, clones your repository into it, installs your plugins, and gives the agent the tools it might need. The machine exists for the thread. When the work is over, you stop thinking about it.

The agent inside an orb is not running on your machine — and yet you control it exactly as if it were. You browse the orb’s files, open a terminal inside it, and review or approve the agent’s changes without pulling anything down. The laptop becomes a window, not the workplace.

That distinction sounds small. It isn’t. On your laptop, agents compete with you for CPU, memory, and attention — so you run one at a time, babysit it, and close it before the fan gets loud. Orbs are infinite by comparison: you can spawn as many as you want, and Amp handles the pausing, waking, and cleanup. No port conflicts, no disk pressure, no worktree hygiene.

the laptop way the orb way

agent · test suite your fan: on queued · migration queued · flake hunt queued · docs

4 tasks × 1 machine = serial hours, blocked laptop

orb 1 · test suite orb 2 · migration orb 3 · flake hunt orb 4 · docs

4 tasks ÷ 4 orbs = one elapsed window, free laptop

Ephemeral

Born with its thread. Paused when idle. Gone when archived. You never name it or nurse it.

Pre-loaded

Your cloned repository, your plugins, and a full dev toolchain are already inside when it starts.

Unsupervised

Built for long builds, big test suites, repo migrations — the work you don’t want to watch.

Infinite-feeling

Spawn one or a dozen. Amp handles pausing, waking, and billing by the minute.

02

Inside an orb

Under the glass, an orb is a Debian 12 box tuned for agentic work. It boots with an authenticated gh, the amp CLI itself, Git and SSH, tmux, ripgrep, fzf, jq, vim, ffmpeg and ImageMagick, PostgreSQL and Redis, Bun, Node.js with npm / pnpm / Yarn, Python with pip, and agent-browser for driving real web pages. Anything missing installs with apt, exactly like any other Debian machine.

Three files in your repository teach orbs how to treat it:

.agents/setup — runs once, while the orb is being prepared. Install dependencies, generate files, seed databases, verify the toolchain. Its log lives at /home/user/.cache/amp/logs/setup.log.
.agents/resume — runs every time the orb wakes. It must be fast and idempotent — a fresh git pull, a cache check — because it gets a 10-second timeout. Log: /home/user/.cache/amp/logs/resume.log.
AGENTS.md — your repository’s guidance for the agent: conventions, gotchas, how to run the tests.

The first time an orb is prepared, the finished sandbox is snapshotted, and that snapshot is reused for new orbs for up to 24 hours. That is why a fresh orb starts fast: it isn’t installing your world from scratch, it’s waking a copy of it.

$ cat .agents/setup
#!/usr/bin/env bash
bun install                        # runs once, while the orb is prepared
psql seed/dev.sql                 # seed the database
$ tail -1 /home/user/.cache/amp/logs/setup.log
setup complete in 94s · sandbox snapshotted (reusable ≤ 24h)

$ cat .agents/resume
#!/usr/bin/env bash
git pull --ff-only                 # runs on every wake · fast, idempotent
$ tail -1 /home/user/.cache/amp/logs/resume.log
resume ok in 1.7s (timeout: 10s)

Illustrative scripts. Your repo defines them; the orb runs them at exactly these moments.

03

A life in seven states

An orb is only ever in one of a handful of states, and every transition is Amp’s job, not yours. The one number to remember is five: after five minutes with nothing to do, an orb pauses itself. A paused orb costs nothing. The moment it’s accessed — a new prompt, a portal request, a teammate opening the thread — it wakes, runs your .agents/resume script, and picks up where it left off.

state: paused · cost · idle timer

This orb is paused. It costs nothing and remembers everything. Give it work to wake it.

time · 1 game-min ≈ 1 s

watch the idle timer count to 5:00 — then it sleeps on its own

1
Create
New thread → a fresh orb is provisioned with your repo, plugins, and tools.
2
Prepare
.agents/setup runs once. The result is snapshotted, reusable for 24 h.
3
Work
The agent runs. Billed by the minute, at the size’s hourly rate.
4
Idle
Nothing to do. A five-minute timer starts. No action needed from you.
5
Paused
Auto-paused — or paused because the thread was archived. Cost: $0.
6
Wake
Any access wakes it instantly: .agents/resume runs (≤ 10 s) and billing resumes.
7
Archive
Archive the thread and the orb pauses for good. Sleep is free; deletion is automatic later.

04

Run a workday

The explainer, as a game. Everything here maps to something true: real sizes, real per-minute prices, the real five-minute auto-pause, and the real difference between one blocked laptop and a parallel fleet. The clock only runs while you’re playing — take all the time you need to think.

// scenario 1 · one long build

CI is red on main. The full end-to-end suite takes 40 minutes and pins whatever runs it. You wanted to ship a feature today. Spawn your first orb, hand it the suite, and keep your machine.

goal: complete all tasks
budget: $1.00
time: unlimited — it pauses when you do

clock09:00

tasks0/1done

spent$0.00of $2.00 budget

orbs00 running

your laptopfreefan off

// backlog 1 task

// fleet empty

No orbs yet. A fleet of exactly zero costs exactly nothing — spawn one to start the clock.

// thread live

// achievements 0/9

First lightspawn your first orb
Parallel lives3 orbs working at once
Paused costs nothingwatch an orb auto-pause
Right-sizedfinish a job on its ideal size
Full fleetrun 5 orbs at once
Under budgetfinish a budgeted scenario in the black
Beat the laptopout-run the local lane
Night shiftclear a day with the lid closed
Orbin’ timefinish every scenario

Prices and behaviour in the game are the real ones: per-minute billing at each size’s hourly rate ÷ 60, auto-pause after five idle minutes, paused orbs free. Game time is compressed; nothing here bills you.

05

Four ways in

Every surface that runs Amp can start an orb. The thread is the orb; there is no extra step.

At ampcode.com, click Create New Thread, pick a project, type your prompt. The orb appears with your repo cloned and your plugins installed — no local setup, nothing on your machine.

01 Create New Thread
02 pick a project
03 type the prompt
✓ fresh orb · repo + plugins inside

From your terminal, -o sends the thread to an orb. Add --orb-size to choose the machine; otherwise your project or workspace default applies.

$ amp -ox "Investigate why the latest CI run on 'main' failed"
thread orb-8f2 · a1.medium · cloning repo…

$ amp -ox "Run the e2e suite on the PR stack" \
      --orb-size a1.xxlarge
thread orb-8f3 · a1.xxlarge · 16 CPU · $1.32/hr

Already inside the Amp TUI? Open the command palette and start a thread in an orb without leaving. Local threads and orb threads sit side by side with the same controls.

> thread:
  thread: new                local
thread: new in orb          ⏎
  thread: open recent
  thread: archive
↵ starts a fresh orb thread

Plugins can spawn orb threads programmatically. An agent finishing one phase of a migration can open the next phase in a fresh orb — machines beget machines.

const thread = await agent.createThread({
  executor: 'orb',          // remote machine
  prompt: 'Migrate the billing module next'
});

// pick a size

a1.small — 2 CPUs, 4 GB RAM, 40 GB disk. $0.17/hr, billed by the minute: $0.0028 per minute.

Set it per thread with --orb-size, as a project default, or as a workspace default for new projects.

06

Remote, yet in your hands

“Remote” is not “hands-off.” Everything you can do with a local agent you can do with an orb — plus a few things you can’t do with a local one.

Review & approve

Watch the diff as it happens and approve the agent’s changes straight from the thread. No pull, no checkout, nothing lands on your machine until you say so.

Browse the files

The orb’s filesystem is a first-class pane. Inspect what the agent changed, open logs, read generated artifacts — all inside the same thread.

Open a terminal

A real shell inside the orb, one click away. Drop in, poke around, run the tests yourself, hand it back to the agent.

Multiplayer

Share an orb with teammates: you, your agent, and your colleagues in the same thread, on the same machine, at the same time.

Sync while it works

Want to iterate alongside the agent? Mirror the orb’s changes to your laptop while the work continues remotely.

amp sync <thread-id>

07

Portals

Anything inside an orb that can listen on a port and speak HTTP can be a portal: a unique, authenticated URL routed to that service. Preview servers, storybooks, APIs — reachable from outside, locked to people who can see the thread.

Declare long-lived services in .amp/services.yaml and bring them up with amp orb services ensure. Each service receives three environment variables: $PORT to listen on, $AMP_THREAD_ID to know its thread, and $PUBLIC_URL — the portal’s address. Services can reference each other’s URLs, so a frontend can point at the API’s portal without knowing anything about the machine.

Two details worth remembering:

Only thread viewers can reach a portal. The URL is authenticated; the public internet can’t knock.
A request wakes a paused orb. Hit the portal of a sleeping orb and it resumes — context intact, billing resumed — then answers.

services:
  - name: web
    command: bun run dev
  - name: api
    command: docker compose up api
$ amp orb services ensure
web  → $PORT=3000  $PUBLIC_URL=https://…amp.site/…
api  → $PORT=4000  $AMP_THREAD_ID=orb-8f2

services.yaml keys shown are illustrative; the env vars, wake behaviour, and auth are the real thing.

08

Beyond one agent

The fleet doesn’t stop at “you, spawning orbs.” Agents, schedulers, and chat can all start work too.

Agents beget agents

An agent can spawn other agents — across orbs, local machines, and remote machines — sharing messages and files to parallelize work, offload chores, and coordinate across projects. Your migration agent can open five fresh orbs, one per module, and merge what comes back.

Automations

Wake agents in orbs at specific times or on regular intervals. They resume with the thread’s full context and history — a nightly verifier that remembers exactly what it verified last night.

Slack

Mention @Amp in Slack to ask questions, fix bugs, and start work without opening Amp at all. The orb takes it from there.

Webhooks

Give an orb an externally available URL and feed it events from CI, GitHub, Linear — anything that can make an HTTP request. The bug report becomes an investigation.

// agent modes

lowmediumhighultra

How much rope the agent gets — from cautious and cheap to fully autonomous. Plan-dependent: Megawatt includes low & medium; Gigawatt unlocks all four.

// runs where you are

webterminalphone

Open and control the same orb thread from your browser, the CLI, or your phone. The conversation stays in sync across all three.

09

The economics

Five sizes, billed by the minute, paused is free. Pick the machine that fits the job — a tiny orb for a script, an xxlarge for a 16-core browser test marathon.

Orb sizes, specifications, and prices
Size	CPU	Memory	Disk	Price	Per minute
a1.tiny	1	2 GB	40 GB	$0.08/hr	$0.0013
a1.small	2	4 GB	40 GB	$0.17/hr	$0.0028
a1.medium	4	8 GB	40 GB	$0.33/hr	$0.0055
a1.large	8	16 GB	40 GB	$0.66/hr	$0.0110
a1.xxlarge	16	32 GB	40 GB	$1.32/hr	$0.0220

enterprise plans: +50% on orb prices

// what would a day cost?

Size

Hours of work 8 hours

Orbs running in parallel 3 orbs

$0.41 3 × a1.small × 8 h — a full workday of a three-orb fleet

on Megawatt ($20/mo): covered by 750 included small-orb hours

Drag the sliders. Notice that a paused fleet costs nothing — idle time never enters this bill because idle orbs sleep.

Megawatt

$20/month

750 hours of small orbs
$20 included agent usage
Low & medium modes
All product features

≈ a small orb running 24/7 for a month

Gigawatt

$200/month

1,000 hours of xxlarge orbs
$200 included agent usage
All modes, incl. high & ultra
Everything in Megawatt

≈ the big machine, every working hour, all month

Unconstrained

PAYG

Pay for what you use
For teams & enterprises
All agent modes
Bring your own keys

when no monthly shape fits

Subscriptions can be supplemented with paid credits; enterprise adds SSO, directory sync, admin controls, minimal data retention, and support — with orb prices 50% higher. A favorite Amp line: they want everyone “living life with parallel agents running in orbs at all times.”

Things change

Why not?

You could already run agents on remote machines — worktrees, SSH, duct tape. But when launching an agent on a machine that isn’t yours is one flag in the interface you already use, next to your local agents, with the same controls… you do it a lot more.

Why not launch eight agents on eight bugs at once, when there are no local resource clashes? Why not turn a bug report into an investigation instead of a ticket? Why not let something run for a very long time, trying every optimization, if it doesn’t eat your CPU? Why not build the prototype? Why not the moonshot?

Why not? — that question is the product. Orbs exist so the answer stops being “my laptop can’t take it.”

ampcode.com · what are orbs? · pricing