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. Delete the cached snapshot from the project settings when you need a setup change to apply immediately.

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. Declare them in .amp/services.yaml instead. See Portals for service configuration and commands.

Installing Software

Orbs run Debian 12 and include common development tools:

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

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

Choose the commit author in the project’s Commit Author setting:

• Amp uses Amp as the author and adds the thread creator as a co-author.
• Thread Creator uses the user who created the thread as the author.

To use another identity, set GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL as personal environment variables. Set GIT_COMMITTER_NAME and GIT_COMMITTER_EMAIL too if the committer must use the same custom identity.

The author is the person who wrote the change. The committer is the person or system that created the commit object. They are usually the same, but they can differ when someone applies another person’s patch, rebases a commit, or amends a commit.

For signed commits, enable Sign Git commits in orbs in your signing key settings and set the project’s commit author to Thread Creator.

Private repositories outside GitHub need clone credentials. Add a secret URL rewrite through Git’s GIT_CONFIG_* environment variables:

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

Replace the host and credentials for your provider. Store the entry containing the token as a secret.

.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

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.