Optimizing Your Codebase for Orbs
An agent in a fresh orb knows only what the orb image, your repository, and your guidance files tell it. Each thing it has to work out by trial and error costs time, and a guess can be wrong. This page lists the changes that let an agent start, run, sign in to, test, and ship your project without guessing.
You do not have to make these changes by hand. Start a thread in your project and ask Amp to make them:
Each section below ends with a prompt for that part of the work. To see the whole process on a real project, watch the Orbs from Zero screencast series.
Checklist
| Recommendation | Where it lives |
|---|---|
| Install only what the orb lacks | .agents/setup |
| Make setup fast and safe to repeat | .agents/setup |
| Keep resume short | .agents/resume |
| Declare your dev servers | .amp/services.yaml |
| Add a development sign-in and seed data | Your app, .agents/setup, .amp/services.yaml |
| Document fast, non-interactive checks | AGENTS.md |
| Write down the house rules | AGENTS.md, .agents/skills/ |
| Store secrets in Amp, not in the repository | Project settings |
| Plan for network access and Git size | Project settings, Tailscale |
| Test it with fresh orbs | A new thread |
Start From the Orb Image
Orbs already include common tools, such as Node.js, pnpm, Bun, Python, uv, Nix, Docker Engine, gh,
and agent-browser with Chrome. Installing Software has the full list. Install only what your project needs and the image lacks, such as another
language runtime, a database server, or a system library. Every extra install makes setup slower.
Pin the versions your project needs even when the image has the tool, because the image’s version
can differ from yours. Have .agents/setup install the versions your project pins, e.g., with mise
for .tool-versions, instead of relying on the image’s versions. Install dependencies from a
committed lockfile with the frozen or locked option.
Orbs run Debian 12 or Debian 13. When a script adds an apt repository, read the release name from /etc/os-release instead of hardcoding it.
Make New Orbs Start Ready
Commit an executable .agents/setup script that installs dependencies and prepares the
environment. On Amp-hosted orbs and self-hosted backends that support snapshots, Amp saves the
result as a project snapshot, so later orbs start from the prepared state instead of repeating the
work. If you cannot commit to the repository, use the Pre-setup Script setting instead. The Orb Lifecycle explains when Amp runs setup and
when it reuses a snapshot.
Make setup safe to run again. A new commit on the base branch, or a change to the project’s shared configuration, makes the snapshot out of date. Amp then runs setup again on top of the previous snapshot, often in the background after a push for workspace projects, otherwise in the next new orb. The script must handle packages, files, and database data that already exist. Check before installing, copy example files without overwriting, and make migrations and seeds safe to repeat. Run the script twice in a row to test this.
Keep setup under about two minutes. Amp stops setup after 20 minutes. Threads show a warning when recent setup runs have taken two minutes or more. To keep setup fast:
- Run independent steps at the same time, such as the database install and the dependency install.
- Print how long each step takes, so
/home/user/.cache/amp/logs/setup.logshows the slow ones. - Do slow work that can be reused in setup, such as installing dependencies, generating code, and warming build caches. The snapshot keeps those files.
Make setup fail loudly and never wait for input. Start the script with set -euo pipefail and pass -y or the equivalent to installers. If setup fails, the orb still starts, but Amp does
not save a snapshot, so every new orb repeats setup until the script is fixed.
Do not leave processes running. Amp stops every process setup leaves behind when the script
exits. On Amp-hosted orbs, start a database or Docker with sudo systemctl enable --now <unit> so
it keeps running in orbs restored from the snapshot. Declare dev servers in .amp/services.yaml,
described in the next sections.
Keep credentials out of setup. Setup receives your workspace and project environment
variables, and the snapshot is usually shared with other project members. See The Orb Lifecycle for the cases where each member gets
their own snapshot. Authenticate with a project-scoped OIDC token, and do anything that needs a
person’s identity in .agents/resume.
A change to .agents/setup applies once it is committed to the base branch. Amp keeps a separate
snapshot for each orb size. In a project with additional repositories, only the primary
repository’s .agents/setup runs, so it must also set up the repositories under ../repos/.
Restore State on Wake
Amp runs .agents/resume when an orb first starts and every time it wakes. Amp waits up to 10
seconds for it before the agent continues. Keep it short, safe to run again, and free of installs.
Use it for work that needs the current person or thread, such as connecting a tunnel, signing in to a service, or mounting storage. See .agents/resume.
On self-hosted orbs that do not keep memory when they pause,
restart local databases in .agents/resume. Amp-hosted orbs keep processes running across a
pause, so they do not need this.
Let the Agent Run Your App
Declare every development server in a committed .amp/services.yaml file. Amp then runs each server
as a supervised service that survives Amp updates, and anyone in the thread can open it from the Portal tab. On Amp-hosted orbs, services also keep running across orb pauses. Opening a declared
portal starts the service if it is not running.
- Make each server listen on
$PORT, and add ahealthpath that returns success only when the app is ready. - Read the public origin from
PUBLIC_URLat runtime. Do not save a portal hostname in configuration. - Route API calls through the frontend dev server’s proxy, because browser requests between two portal hosts are not supported.
- Add
.amp/portals/to.gitignore. Amp writes generated files there.
Portals covers the file format and framework settings, such as allowed hosts for Vite and Laravel.
If your app needs several steps to start, put them behind one command that is safe to run again,
and name that command in AGENTS.md. The agent should not have to work out what state the server
is in.
Let the Agent Sign In
Sign-in flows with OAuth, email links, or two-factor codes stop agents and reviewers alike. Add a
development-only route that signs the browser in as any test user, and make it the primary portal
link with $AMP_USER_EMAIL. See Dev Magic Link Authentication.
Seed predictable test data in setup, such as an admin user, a regular user, and enough records to show each page. The agent should never have to create accounts or reset passwords to get started. For states that are hard to reach by hand, such as a brand-new user, add portal links that set them up, and group them in a portal folder.
When the app depends on a third-party service, let it run with test data when that service’s secret is missing. A fresh orb can then start the app before anyone adds the secret.
List the development-only routes and test accounts in AGENTS.md, so a new agent finds them
without a hint.
Let the Agent Check Its Work
List the exact commands in AGENTS.md for formatting, linting, type checking, the full test
suite, and a single test file. Say how long each usually takes, so the agent waits for a slow
suite instead of assuming it is stuck.
Make every command finish on its own. Agent commands run without a terminal and with input
closed, so a prompt, a pager, or a watch mode that waits for a key never ends. Commands run with AGENT=amp set, so a script can check it and change its behavior.
Keep tests self-contained. They should use the services that setup installs, not shared cloud resources or one developer’s credentials.
The default Ship flow runs the full test suite before every push, so the suite’s run time is part of every ship. If the suite is long, choose a larger orb size for the project, use a remote build cache with its token in project secrets, or name a faster check in a custom Ship prompt.
When the agent pushes to GitHub, it can follow CI for that commit and fix failures it caused. Give CI jobs clear names and readable failure logs to help it.
For UI work, give the agent something it can screenshot, such as a component preview page behind a
portal. Write server logs, and browser console logs if you can, to one file the agent can search.
For iOS and Mac apps, pin the Xcode version in .xcode-version; see macOS Satellites.
Tell the Agent the House Rules
Use AGENTS.md to describe the project in a way a new agent can act
on. A root file covers the whole repository, and a file in each package covers that package.
Include:
- What the project is and how its parts fit together
- How to start, sign in to, and test the app
- Where logs are written
- What the agent must not do
For facts that are only true in an orb, add an “In an Orb” section to AGENTS.md, or have setup
write them to ~/.config/amp/AGENTS.md. Orbs ship a default file at that path, so add your lines
to it instead of replacing it. Setup runs again on top of earlier snapshots, so add them only if
they are not already there. Scripts can check AMP_ORB=1 to detect an orb.
Commit skills under .agents/skills/ for workflows with several steps,
such as starting the dev server or testing in a browser. Put delivery steps, such as opening a pull
request, in the project’s Ship prompt.
Give Access Without Storing Keys
Store values in Amp settings, not in the repository. Use project values for what every orb needs and personal values for what is yours. Mark tokens as secrets. Prefer OIDC to stored keys where the service supports it. See Handling Secrets.
Commit an example environment file whose variable names match the names you store in Amp, and have setup copy it without overwriting. The agent can then see which values are missing.
Network Access and Git
Orbs can reach the internet. On Amp-hosted orbs, their outbound IP addresses change. To reach a private service or an API that allows only known addresses, connect the orb with Tailscale. For websites that block cloud IP addresses, use Orb Network Routing through an Amp runner.
Amp clones the full history of the base branch and skips file versions larger than 1 MB until a command needs one. A clone that takes longer than 15 minutes fails. Keep large binary files out of Git history, or turn on Shallow Clone as described in Git History.
In some cases, such as repositories on Git hosts other than GitHub.com and GitLab, or when Amp cannot read the latest base-branch commit, Amp keeps a snapshot for each project member and runs setup on every new orb. A fast setup script helps these projects most. See The Orb Lifecycle.
On self-hosted orbs, bring your own image with the
tools that every project needs, such as internal CA certificates, and keep project steps in .agents/setup.
Check That It Works
Test the result the way a new agent meets it. Push your changes to the base branch, then ask Amp to start a few fresh orbs with tasks that give no hints, and to report how each agent did the work:
Fix the guidance wherever an agent guessed or got stuck, and run the test again. Also read /home/user/.cache/amp/logs/setup.log to see which setup steps are slow.
