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.

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 pane 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.

Follow Along From Your Mac or iPhone

Because the agent works in an orb and not on your computer, you can use any device to check on it. The macOS and iOS apps show the same threads as ampcode.com, and they 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 onto the Terminal pane. 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. Pass a thread URL or ID:

amp sync <thread>

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.