Getting Started With Orbs

An orb is a remote machine that Amp creates for a thread. It has your code, your tools, and a full development environment, and the agent works there instead of on your computer. Read the Orbs overview for what orbs are and why you would use one.

This page walks you through creating your first orb thread:

1. Sign in
2. Create a project so Amp knows which repository to use (optional)
3. Send a prompt to start the agent in an orb
4. Prepare the repository so every new orb starts ready to work (optional)
5. Explore what else orbs can do

1. Sign In

Sign up or sign in at ampcode.com. The orb runs in Amp’s cloud, so you do not need to install anything.

If your code is in a private GitHub repository, connect GitHub in your integration settings. Amp uses that connection to clone the repository into the orb.

2. Create a Project

A project connects a repository to Amp. It tells Amp which repository to clone into the orb and holds the settings that every orb for that repository shares, such as secrets and the orb size. Read Projects for everything a project can hold.

1. Open Projects and click New Project.

2. Choose where the code comes from:

   • Use an Existing Repository. Pick a repository from your GitHub connection, or paste the URL of a public repository from any Git host. Public GitHub repositories work without connecting GitHub. Private repositories on other hosts need clone credentials. See Other Git Hosts below.
   • Start From Scratch. Amp creates and hosts a blank repository for you.

3. Then pick an owner. A workspace project is visible to your teammates. A private project is visible only to you. If the work spans more than one repository, click Add Additional Repositories. You can also change this later in the project settings.

If you don’t need your code in the orb, you can skip this step. Select No Project when you start a thread to get a clean orb without a repository. This is useful for research, one-off scripts, or work that starts from attached files instead of code.

Other Git Hosts

Public repositories on GitLab, Bitbucket, and other hosts work with just the HTTPS URL. Private repositories on those hosts need credentials so the orb can clone them. Add them as a secret Git URL rewrite in the project’s environment. See Configure Git for the exact variables.

3. Send a Prompt

Open ampcode.com and click New Thread. The composer shows where the thread runs, which project it uses, and which mode the agent works in. Make sure the executor says New Orb and pick your project.

Then describe the result you want. Ask for a complete result: the agent has a whole machine, so it can run your app and test its work before it reports back. For example:

Press Enter to send the prompt. Amp creates an orb, clones the repository, and starts the agent. The first orb takes a little longer; later threads in the project reuse a snapshot and start faster. While the agent works, the panes next to the thread show its changes, portals, files, and a terminal in the orb.

You can close your laptop at this point. The agent keeps working, and the orb goes to sleep when the agent is done. When you send the next message, it wakes up with your files and services still in place.

4. Prepare the Repository for Orbs (Optional)

The first thread in a project starts from a plain orb. The agent can install whatever it needs as it goes, but every new orb would repeat that work. To avoid it, add two scripts to the repository:

• .agents/setup installs dependencies and tools. Amp runs it once when it prepares a new orb and saves the result as a snapshot for later threads.
• .agents/resume runs after every wake. Use it for quick work such as refreshing a login or restarting a service.

The fastest way to add them is to let Amp do it. After creating the first thread, reopen New Thread for the project and click Set Up with Amp in the Set Up Orbs notice. The same notice is on the project page if you dismissed it.

Amp opens a new thread with a prompt that asks the agent to write both scripts, run them in the orb to make sure they work, and commit them. You can also type that request yourself:

The new files show up in the Changes pane, where you can review them. The prompt asks the agent to commit them. If it has not, or if you changed them, click Ship to commit and push. See Shipping Changes to change what Ship does for your project. From then on, Amp runs .agents/setup when it prepares the project snapshot, and every new orb for this project starts from that prepared state.

A few more settings live in the project settings and apply to every orb in the project:

• Secrets & Env Vars holds API keys and other configuration the agent needs. Values are encrypted, and personal values override project values. See Handling Secrets.
• Orb sets the default machine size. See Sizes & Costs.
• Commit an .amp/services.yaml file to declare dev servers the agent should start and expose. See Portals.

Read Customizing Orbs for how snapshots work, what each script should and should not do, and how to read the setup logs.

5. Explore

Once your first thread is running, try the other things orbs can do:

• Customizing Orbs explains the orb lifecycle, setup and resume scripts, and how to install software that every orb needs.
• Portals let you open a web server running inside the orb from the thread, and send comments on what you see straight to the agent.
• Multiplayer lets your teammates join a thread and work in the same orb with you.
• Agent to Agent lets an agent start other agents in their own orbs, hand them work, and bring the results back.
• Automations let a thread keep working later or on a schedule, in the same orb.
• Event-Driven Orbs let an outside service, such as GitHub, wake an orb through a webhook.

You can also start orb threads without the browser: run amp -ox "your prompt" in the CLI, or select thread: new in orb in the TUI command palette.