Orbs are machines in which an agent can run without supervision. When you create a new thread you get a fresh orb that contains your code, plugins, and tools the agent might need.

What Are Orbs?

Orbs are remote machines where Amp agents can run without supervision. Each Amp thread started from ampcode.com in an orb gets its own orb.

Each orb starts with a fresh clone of your repository, access to your project configuration.

An orb can have up to 32GB of memory and 16 CPUs.

Pricing

You can choose the orb size for each project in project settings:

a0.tiny: 1 CPU, 2GB memory, 40GB disk ($0.10/hour)
a0.small: 2 CPUs, 4GB memory, 40GB disk ($0.21/hour)
a0.medium: 8 CPUs, 16GB memory, 40GB disk ($0.83/hour)
a0.large: 16 CPUs, 32GB memory, 40GB disk ($1.66/hour) — default

Orbs are billed by the minute. A paused orb does not cost anything.

Orbs are auto-paused when inactive (15 minutes after no activity) and paused immediately when their thread is archived. You never need to manually pause them.

Prices for enterprise workspaces are 50% higher.

Getting Started

You can start orb threads from the web, CLI, or TUI:

On ampcode.com, click Create New Thread, select a project, enter a prompt, and submit.
In the CLI, run amp -ox “your prompt”.
In the TUI command palette, run thread: new in orb.
In a plugin, call agent.createThread({ executor: 'orb' }).

This will spawn a new orb, clone your repository, and start the agent in it.

Features

Review & File Access

Review the agent’s changes and browse files directly from the orb without syncing anything to your laptop first.

Terminal

Select the Terminal pane in an orb thread to open a shell directly inside the orb. The terminal shares the orb’s filesystem and working copy with the agent, so you can inspect or edit files, add local configuration, install dependencies, run tests, and debug processes. Filesystem changes are immediately available to the agent.

The terminal runs in a tmux session shared with the agent, so the agent can see the terminal output and collaborate in the same shell session.

`amp sync`

Run amp sync <thread-id> to mirror an orb thread’s changes into your local checkout while the agent keeps working remotely.

`amp -ox`

Run amp -ox “your prompt” to start a new execute-mode thread in an orb from the CLI.

Start Orb Threads from the TUI

Create orb-backed threads from the Amp TUI when you want the agent to run remotely but stay in your normal terminal workflow.

Choose a Project from the TUI

Use project: select to choose the project for your next orb thread. If you need to create a new project first, use project: create.

Secrets & Env Vars

Project settings let you define environment variables and secrets for agents running in orbs. Open your project on ampcode.com, go to

Settings, then add the values your setup scripts, tools, and app need at runtime.

For one-off changes to files or local configuration in a running orb, use the Terminal pane to edit them directly.

Project settings page showing environment variables and secrets for orbs

OIDC Workload Identity

An orb can mint a short-lived OIDC token that identifies its workspace, project, user, and thread. Use it to federate with cloud providers and internal services instead of putting long-lived credentials in project settings:

amp orb id-token --audience my-service

The audience must identify the service that will verify the token. See OIDC from Orbs for complete Google Cloud, Tailscale, and AWS federation recipes.

Projects

Projects are how Amp knows what code and configuration an orb should use. Threads started from a project get a fresh orb clone of that repository, and any setup files committed to the repo run as part of preparing the orb.

Project-wide settings such as the repository identity and changes workflow are covered in the main manual’s Projects section.

What's In An Orb?

Orbs run Debian 12.

Orbs already come with common agent and development tools pre-installed:

Authenticated gh and amp
Git and SSH
PostgreSQL 17 and Redis
tmux, ffmpeg, ImageMagick, vim, jq, fzf, unzip, zstd, lsof, and websocat
ripgrep and ast-grep
Bun, Node.js, npm, pnpm, and Yarn
Python and pip
agent-browser

Use apt or apt-get to install system packages, and pnpm for JavaScript dependencies.

Git Commit Signing

If you need signed Git commits in orbs, enable

Sign Git commits in orbs in your personal signing key settings. Your project must use Thread Creator as its Orb Commit Author.

Setup Files

Put these files in the repository, commit them, and keep them short. Amp runs .agents/setup and .agents/resume as repository lifecycle hooks from the repo root.

File	What it does
`.agents/setup`	A shell script Amp runs from the repo root before starting work in a fresh orb. Use it to install dependencies, prepare generated files, or check required tools. Make it executable.
`.agents/resume`	A shell script Amp starts from the repo root whenever an existing orb resumes before the agent continues work. Amp waits up to 10 seconds for it; if it is still running, Amp stops blocking and lets it continue in the orb. Use it for fast, idempotent reconnect or repair steps such as restarting tunnels. Make it executable.
`.amp/services.yaml`	Declares long-lived dev servers/services; `amp orb services ensure` runs them supervised and exposes their portal URLs. See Portals.
`.amp/portals/*.json`	Portal-tab manifests. They define links (each with an optional note) Amp can show after a portal server is available.

Examples

Minimal .agents/setup:

#!/usr/bin/env bash
set -euo pipefail

corepack enable
pnpm install --frozen-lockfile
[ -f .env.local ] || cp -- .env.example .env.local

Then commit the executable bit:

chmod +x .agents/setup

Minimal .agents/resume:

#!/usr/bin/env bash
set -euo pipefail

# Fast, idempotent repair work only. Do not install dependencies here.
mkdir -p .amp
date > .amp/resume-last-ran.txt

Amp blocks on .agents/resume for at most 10 seconds. If the hook finishes within that window and exits non-zero, Amp surfaces the failure before continuing. If it is still running after 10 seconds, Amp continues and leaves the hook running in the orb; write progress and diagnostics to logs rather than relying on the agent to wait.

Then commit the executable bit:

chmod +x .agents/resume

Portals

This is an experimental feature. Enable it in your Advanced Settings.

Portals are authenticated URLs that expose web servers running inside an orb, so you can open a dev server or preview app straight from the thread’s Portal tab. The easiest way to set one up is to ask the agent: “start the dev server and give me a portal link.”

Declaring Services

Commit .amp/services.yaml to declare your repository’s dev servers (usually the agent writes this file for you):

services:
  web:
    command: pnpm dev
    access: any-amp-user
    portal:
      title: App
      description: Use the seeded test account.

amp orb services ensure starts each declared service supervised, so it survives Amp CLI updates and orb pause/resume. Each command runs with $PORT set and must listen on that port; a portaled service also receives its public URL as $PUBLIC_URL. When port is omitted, Amp picks a free port that stays sticky across restarts. HTTPS servers are detected and bridged automatically.

amp orb services ensure also writes the Portal tab’s links to .amp/portals/*.json. To add custom links, write a manifest by hand. Get each URL from amp orb portal 3000 (pass the local port) instead of hardcoding the domain format:

{
  "links": [
    { "label": "App", "url": "https://t-…-p3000.onamp.dev", "note": "Use the seeded test account." },
    { "label": "Admin", "url": "https://t-…-p3000.onamp.dev/admin" }
  ]
}

A link’s optional note is shown as an info popover next to it.

For an app with separate frontend and API services, expose the frontend portal and route API requests through the frontend dev server’s proxy (for example, Vite’s server.proxy). Cross-origin requests between two portal hosts are not supported because browser CORS preflights do not carry portal authentication. (We may have other solutions in the future.)

Access

Opening a portal always requires signing in to Amp. By default (access: same-as-thread), only viewers who can access the thread can open it. Set access: any-amp-user on a service to let any signed-in Amp user with the URL open it; this does not grant access to the thread itself.

Any HTTP request to a portal wakes a paused orb and resumes billing until the orb pauses again (15 minutes after no activity). The sign-in requirement keeps anonymous bots and scanners from waking your orb.

Requests from Inside the Orb

Inside the owning orb, requests to that thread’s portal URLs hairpin directly to the local service instead of leaving the orb, so $PUBLIC_URL works out of the box for curl, Node, Python, and browser automation running in the orb—no extra authentication needed.