Orbs

Orbs are remote machines where Amp agents work without using your computer. Every orb thread gets a fresh, isolated environment with your code, plugins, development tools, and the context of the thread that created it.

See What Are Orbs? and Orbs, Explained for overviews of what orbs are and how they can change how you build, and Putting an Agent in an Orb to learn how to prepare your codebase for orbs. To watch it done on a real project, see the Orbs from Zero screencast series.

Why Use an Orb?

An agent in an orb keeps working while your laptop is closed. The orb takes up nothing on your machine, so you can start several independent tasks at once and let each one run for as long as it needs.

You also do not have to manage the machine. When the agent is done, the orb goes to sleep, and a sleeping orb costs nothing, even if it sleeps for weeks. When you send another prompt, the orb wakes up with your conversation, files, and services still in place. An orb pauses a few minutes after the agent finishes and you stop interacting with it. See When an Orb Pauses for the exact timeouts.

That also changes what you can ask for. The agent has a whole machine to itself, so it can install dependencies, run your app, spawn browsers, and test its work end to end. Tell it to prove that its changes work before you look at them. When the work is ready, the thread contains the conversation, the code changes, the running services, and the proof, which is everything you need to review the result.

Orb Spawn Pacing

Each user can start a burst of 20 metered orbs. After that burst, Amp starts one new orb every five minutes. Later orb starts wait instead of failing. The thread shows the estimated wait and starts the orb when capacity is available.

If you need a higher limit, contact Amp support.

Review Changes and Browse Files

Open the thread’s changes view to review the diff. You can also browse and open any file in the orb without downloading the repository first.

Use the Terminal

Open the Terminal tab to get a shell inside the orb. The terminal and the agent use the same filesystem and working copy, so changes made in either place are immediately visible in the other. Use it to inspect processes, change local configuration, install a dependency, or run a command alongside the agent.

The terminal runs in a shared tmux session. Amp can inspect its output and work with long-running commands in the same session.

Amp can also embed the terminal live in its reply, so you can type into it without leaving the conversation.

Follow Along From Your Mac, iPhone, or Android Phone

Because the agent works in an orb and not on your computer, you can use any device to check on it. The macOS, iOS, and Android apps show the same threads as ampcode.com, and the macOS and iOS apps notify you when a thread is ready for your next message. Start a task at your desk, then review the result, answer a question, or send the next prompt from your phone.

Upload Files to an Orb

There are three ways to get a file from your computer into an orb:

  • Attach it to the thread. Use the attachment button in the message composer, drag the file into the composer, or paste it. The agent sees the attachment and can download it into the orb when it needs to. See Files & Attachments.
  • Upload it through the Files pane. Drag a file from your computer onto the Files tab to upload it directly into the orb’s file system. Drop onto a directory to upload into that directory, or anywhere else in the pane to upload into the repository root. You can also click the upload button in the pane’s toolbar to pick files for the repository root, or right-click a directory and choose Upload Files… to pick files for that directory.
  • Paste or drop it into the terminal. Paste an image or drop a file into the Terminal tab. Amp uploads the file to the orb and inserts its absolute path at the cursor, so you can pass a screenshot or a document to a command or to an agent CLI running in the terminal. Pasting text works as usual; only clipboards that hold a file and no text are uploaded.

Files uploaded through the Files pane or the terminal can be up to 512 MB each. Thread attachments follow the attachment size limit.

Sync Changes to Your Computer

Use amp sync to mirror an orb thread’s changes into your local checkout while the agent keeps working remotely. Run it inside a clone of the thread’s repository and pass a thread URL or ID:

amp sync <thread>

amp sync needs a checkout with no uncommitted changes. It checks out the orb’s commit, copies the orb’s uncommitted changes, and keeps your checkout updated as the agent works. Commits the orb has not pushed come straight from the orb, so the agent does not need to push first. When you stop amp sync, it resets your checkout to where it was before, so do not edit files locally while it runs.

To pick the command up from the web, choose Orb → Copy Sync CLI Command from a thread’s More Actions menu.

Copy an Orb’s Work Once

To keep a copy of the orb’s current work, pass --apply:

amp sync --apply <thread>

This checks out the branch the orb is on at the orb’s latest commit, applies the orb’s uncommitted changes, and exits. Your checkout keeps the result. Run it again to pick up newer work.

Use it to move an orb’s work onto another machine, such as a GPU server or a CI machine, without a GitHub mirror and without asking the agent to push. Clone the repository once, with amp clone for an Amp-hosted project or git clone otherwise, then run amp sync --apply inside the clone whenever you want the latest work:

amp clone owner/project-name
cd project-name
amp sync --apply <thread> --checkout

If your checkout has no uncommitted changes, --apply switches to the orb’s branch without asking. Otherwise it asks first. Pass --checkout to switch without asking, which scripts need, or --skip-checkout to stay on your current commit and apply only the orb’s uncommitted changes.

amp sync signs in as you. Run amp login first, or on a machine without a browser set AMP_API_KEY to an access token. To fetch only work that has already been pushed to an Amp-hosted project, without signing in as yourself, use a read-only Git credential.

Start an Orb From the CLI

Use amp -ox to start an execute-mode thread in an orb without leaving your terminal:

amp -ox "Investigate why the latest CI run on main failed"

Use --orb-size when the task needs a different amount of compute from the project default:

amp -ox "Run the performance test matrix" --orb-size a1.large

See Sizes & Costs for the available sizes, and Spawning Orbs for choosing the project, continuing an existing orb thread, and streaming output from an orb.

Start an Orb From the TUI

Open the command palette with Ctrl+O and select thread: new in orb. To choose the project first, select project: select. Use project: create if the repository does not have an Amp project yet.

Next Steps

Read Getting Started to create your first orb. Then customize the environment for your repository or share a running service with Portals.