--- lastModified: 2026-09-14 --- # 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?_](/what-are-orbs) and [_Orbs, Explained_](/notes/orbs-explained) for overviews of what orbs are and how they can change how you build, and [_Putting an Agent in an Orb_](/notes/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_](/docs/using-amp/screencasts/orbs) 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](/docs/orbs/sizes-and-costs#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](/docs/support/getting-help). ## 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 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](/docs/macos-and-ios) 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](/docs/orbs/files-and-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](/docs/orbs/files-and-attachments#attach-a-file). ## 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: ```bash amp sync ```

## Start an Orb From the CLI Use [`amp -ox`](/docs/cli/spawning-orbs) to start an execute-mode thread in an orb without leaving your terminal: ```bash 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: ```bash amp -ox "Run the performance test matrix" --orb-size a1.large ``` See [Sizes & Costs](/docs/orbs/sizes-and-costs) for the available sizes, and [Spawning Orbs](/docs/cli/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](/docs/orbs/getting-started) to create your first orb. Then [customize the environment](/docs/orbs/customizing) for your repository or share a running service with [Portals](/docs/orbs/portals).