Customizing Orbs

You customize the orb lifecycle with two executable files:

• .agents/setup prepares new project orbs and the snapshots used to start them.
• .agents/resume authenticates, repairs, or reconnects an orb after activation and after each wake.

Both files are optional. Commit them to the repository. Amp may run either file more than once, so each script should check what is already installed or configured before changing it.

In project settings under Orb, you can also set scripts that Amp stores outside the repository:

• Pre-clone script runs from /home/user/workspace before Amp clones or updates repositories. Use it for prerequisites required to access the repositories. A failure stops orb setup.
• Pre-setup script runs immediately before .agents/setup whenever setup runs.

Pre-clone, pre-setup, and .agents/setup can mint project- or workspace-scoped OIDC tokens. This lets setup authenticate to shared services without storing a long-lived secret. See Handling Secrets.

The Orb Lifecycle

A snapshot is a saved copy of a prepared orb. It contains the repository and anything changed by .agents/setup, such as installed software. Amp uses snapshots so every new thread does not need to repeat the same setup work.

When you start a project orb, Amp follows this flow:

1. Amp checks for a project snapshot for the selected orb size.
2. If the snapshot matches the current repository source and shared configuration, Amp restores it and skips .agents/setup.
3. If no matching snapshot exists, Amp starts from a base or older snapshot, runs the pre-clone script, clones or updates the repositories, then runs the pre-setup script and .agents/setup from the repository root.
4. If setup finishes successfully, Amp saves the prepared orb as the new project snapshot.
5. Amp applies the current thread environment and workload identity credentials.
6. Amp runs .agents/resume, then starts the agent.

Amp can reuse a matching project snapshot for up to 72 hours. It refreshes the snapshot when it is too old or no longer matches the project source and shared environment. Changes to .agents/setup do not invalidate an existing snapshot by themselves. When you need a setup change to apply right away, delete the cached snapshot from the project settings or run:

amp projects snapshots list <project>
amp projects snapshots delete <project> --resource a1.small

Omit --resource to delete every snapshot for the project.

When an existing orb wakes, Amp restores its executor and runs .agents/resume again.

.agents/setup

Add an executable .agents/setup shell script at the repository root. Use it to install the dependencies and software needed in every orb. You can also use it to generate files or check that required tools are available.

In multi-repository projects, Amp checks out additional repositories under ../repos/ relative to the primary repository root directory. Amp runs only the primary repository’s .agents/setup script, so initialization of any other repositories should be kicked off by this script.

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

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

Commit the executable bit:

chmod +x .agents/setup
git add .agents/setup

Keep setup fast and idempotent. A person or agent should be able to run it again without damaging the environment. Amp stops setup after 20 minutes and continues starting the orb. If setup fails or times out, Amp does not publish a refreshed project snapshot, so a later fresh orb may run setup again.

Amp may save the result of .agents/setup in a project snapshot and reuse it for another thread or project member. Setup does not receive personal or thread workload identity. It can mint a stable project or workspace identity instead:

amp orb id-token \
  --audience https://service.example.com \
  --subject-scope project

Amp makes the setup request credential available before the pre-clone script and removes it after setup, before saving the snapshot. Do not copy tokens, provider credentials, or login caches to another file during setup. Authenticate services that need a user or thread identity from .agents/resume, which receives a fresh runtime credential.

Do not start development servers or other long-running processes in .agents/setup. Amp stops every process the script leaves running when it exits, including commands started with &, nohup, or setsid, and daemons that a tool started on its own. None of them reach the snapshot. Use one of these instead:

• Declare development servers and other processes the agent needs in .amp/services.yaml. A service does not need a portal. See Portals for the configuration and commands.
• Start a system service that a package installed, e.g., a database or a VPN daemon such as tailscaled, with sudo systemctl enable --now <unit>. Systemd owns it, so it survives setup and starts again in every orb restored from the snapshot.
• Do slow but finite work, e.g., a font download or a cache warmup, in the foreground and let setup wait for it. Anything still running when the script exits is lost.
• Start work that only needs to be done by the time someone opens a portal, which can be many minutes after setup, from .agents/resume instead. Processes that .agents/resume starts keep running after the script exits and are not stopped. Make the script idempotent, because Amp runs it again every time the orb wakes.

Installing Software

Orbs run Debian 12 and include common development tools:

• amp and gh, authenticated after orb activation
• Git, SSH, and tmux
• Bun, Node.js, npm, pnpm, and Yarn
• Python, pip, and uv
• agent-browser
• ffmpeg, ImageMagick, jq, fzf, ripgrep, vim, unzip, zstd, lsof, and websocat

Pre-clone, pre-setup, and .agents/setup do not receive your personal GitHub credentials, so gh is not authenticated while those scripts run. Use .agents/resume for commands that need the current user’s GitHub authentication.

Install project dependencies and software that every orb needs from .agents/setup. Check whether a system command already exists before installing it so the script stays fast when run again:

if ! command -v shellcheck >/dev/null 2>&1; then
	sudo apt-get update
	sudo apt-get install -y shellcheck
fi

Software installed manually from the Terminal is available only in that orb. Put the installation in .agents/setup when future orbs need it too.

Docker is not installed by default. Install it from .agents/setup, then run the daemon as a supervised orb service. Do not start the daemon from the setup script.

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

if ! command -v docker >/dev/null 2>&1; then
	sudo install -m 0755 -d /etc/apt/keyrings
	sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
	sudo chmod a+r /etc/apt/keyrings/docker.asc
	echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
	sudo apt-get update
	sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
fi

amp orb service start docker-daemon --command 'sudo dockerd'
sudo docker run hello-world

To share a containerized web server, publish its port with -p and expose that port with a portal.

Configure Git

GitHub repositories need no Git setup in the orb. Amp clones, fetches, and pushes with your GitHub connection, and your Git identity and signing key settings decide how commits are attributed and signed. See GitHub & Git for how that works.

Private repositories outside GitHub need clone credentials. Configure them before starting the first thread in your project:

1. In project settings, set Git Repository to the repository’s HTTPS clone URL, such as https://git.example.com/team/repo.git. Do not include a username or token in this field.
2. Under Secrets & Env Vars, add the following as three separate entries. The text before the first = is the entry name, and the rest is its value. Mark GIT_CONFIG_KEY_0 as a secret because its value contains the token.

GIT_CONFIG_COUNT=1
GIT_CONFIG_KEY_0=url.https://USERNAME:TOKEN@git.example.com/.insteadOf
GIT_CONFIG_VALUE_0=https://git.example.com/

3. Replace git.example.com in both values with the hostname from your clone URL. Replace USERNAME and TOKEN with the username and token specified by your Git provider. Some token types require a fixed username rather than your account name. URL-encode any special characters in the username or token.
4. Keep url., /.insteadOf, and the trailing / exactly as written. Do not replace them with the repository name. This tells Git to authenticate HTTPS requests to that host using the credentials in the secret.
5. Save the settings, then start a thread in the project.

If a thread already shows Repository Setup Failed, open Setup Log to inspect the error. Correct the repository URL or credentials in project settings, save them, then start a new thread in the same project. Its new orb attempts the clone with the updated settings. Remove credentials before sharing any log output.

.agents/resume

Add an executable .agents/resume shell script for quick authentication, repair, or reconnection work. Amp runs it after the current thread environment and workload identity credentials are available. It runs once after initial activation and again whenever the orb wakes. Use it for short tasks such as:

• Authenticate or refresh a tunnel.
• Check a mounted dependency.
• Restore local state that does not survive a pause.

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

mkdir -p .amp
date > .amp/resume-last-ran.txt

Amp waits for .agents/resume for up to 10 seconds before the agent continues. If the hook is still running, Amp lets it continue in the orb without blocking the agent. Keep the blocking work short and write progress to a log rather than expecting the agent to wait. Do not install dependencies in this hook.

For example, install Tailscale and its system configuration from .agents/setup. Then run tailscale up from .agents/resume so each orb authenticates with the current thread’s workload identity.

Run the hook again safely whenever the same repair is needed:

chmod +x .agents/resume
git add .agents/resume

Mount External Storage

Orbs support any Linux FUSE file system. You can mount external storage when you want to share volumes across orbs or increase the storage available to an orb beyond its maximum.

Archil provides a cloud-based shared POSIX file system that orbs can mount as a regular directory. To use it, give Amp a link to this section, and it will walk you through the rest.

if ! command -v archil >/dev/null 2>&1; then
	curl -fsSL https://archil.com/install | ARCHIL_SKIP_IAM_CHECK=1 sh
fi

: "${ARCHIL_MOUNT_TOKEN:?Set ARCHIL_MOUNT_TOKEN in Amp secrets}"
: "${ARCHIL_DISK_ID:?Set ARCHIL_DISK_ID in Amp environment variables}"

mountpoint=/home/user/archil
if ! findmnt -n "$mountpoint" >/dev/null; then
	sudo mkdir -p "$mountpoint"
	sudo --preserve-env=ARCHIL_MOUNT_TOKEN \
		archil mount "$ARCHIL_DISK_ID" "$mountpoint" --region "${ARCHIL_REGION:-gcp-us-west1}"
	sudo chown "$(id -u):$(id -g)" "$mountpoint"
fi

Pre-setup Script Setting

The Pre-setup Script project setting holds a script that Amp runs from the repository root right before .agents/setup. Use it to set up orbs without committing anything to the repository.

Like .agents/setup, this script can run amp orb id-token with --subject-scope project or --subject-scope workspace. The same setup credential is available to the pre-clone script before the repository exists.

The simplest way is to start a thread in the project and ask:

Amp writes and tests the script in the orb and stores it in project settings. New orbs pick up changes to the script automatically, so you can keep asking Amp to change it.

You can also edit the script under Orb in project settings, or with the CLI:

amp projects update <namespace/name> --pre-setup-script-file ./pre-setup.sh

If the project also needs .agents/resume or .amp/services.yaml and you do not want to commit them either, have the pre-setup script write them into the checkout and add them to .git/info/exclude so they stay out of git status.

Store values the pre-setup script needs as project environment variables or secrets, not in the script itself.

Read Hook Logs

Amp writes standard output and standard error from each hook to a file in the orb. It replaces the file each time the hook runs.

Ask Amp to inspect these files when an orb fails to prepare or resume.