Thorsten Ball//July 02, 2026

Putting an Agent in an Orb

After releasing Agents in Orbs on Tuesday we’ve been asked: how do you check what the agent did in a remote machine, don’t you miss your local development environment for that?

The answer is: sometimes, and less and less so.

Not only is the current generation of frontier models incredibly good at checking their own work, even in a remote machine, but with some additional tooling and documentation, they can go a very long way.

We’ve been continuously optimizing our Amp codebase to be more agent-friendly, and it’s now gotten to a point where if you had told me half a year ago that it would be possible for an agent to do that, on a headless remote machine, an orb, I wouldn’t have believed you.

Here’s an example. I asked Amp to find a button in our amp repository and show me a screenshot of it in different configurations:

After a couple of minutes, it came back with exactly what I had asked for:

Here I asked it to do a full run-through of our core functionality:

And, again, after a few minutes it came back with proof:

Note that in both cases I didn’t specify how the agent should go about doing any of that. I didn’t specify how to start the dev server, how to login, how to use the CLI, how to take screenshots. It figured it out by itself.

It’s all in the codebase, the tooling, the documentation, and the orb.

Let’s start with the orb.

What’s in an Orb?

Every orb runs Debian 12 and comes with a lot of tools already: authenticated gh (the GitHub CLI) and amp, PostgreSQL and Redis, tmux, ffmpeg, ImageMagick, ripgrep, Bun and Node.js, npm and pnpm, agent-browser, and a few other things. You can find the complete list here.

In the Amp system prompt, we tell the agent that it’s running inside an orb and how to get more tools. Nearly everything is an apt-get install away.

That’s already enough for an agent to go a long way. But our codebase needs our toolchain, our database, our dev server. That’s where the orb setup files come in.

.agents/setup

Every time a fresh orb is created, Amp runs .agents/setup in the repo root. See this section in the manual for examples. (Mind you: that’s a note for your agent rather than yourself.)

In our amp repository, the .agents/setup file is currently a 428 line long Bash script that does the following:

  • Start PostgreSQL and create the amp user and database. Since orbs are ephemeral, we tune it for speed over durability: fsync = off,synchronous_commit = off, autovacuum = off.
  • Seed the database with test users.
  • Install mise and run mise install --locked, so the orb gets the exact Node and pnpm versions from our mise.lock. Those might be newer than what’s in the base image.
  • Run pnpm install --frozen-lockfile.
  • Install the odd extras our tooling wants that the base image doesn’t have: Pillow (our agent guidance tells agents to measure screenshots with PIL instead of eyeballing pixels) and sqlite3.

It also writes orb-specific guidance into ~/.config/amp/AGENTS.md, which the agent will read alongside the AGENTS.md files in the repo:

local amp_config_dir="$HOME/.config/amp"
mkdir -p "$amp_config_dir"

cat >"$amp_config_dir/AGENTS.md" <<'EOF'
# Inside the Orb

- This orb may have an older system `node` and `pnpm`; `.agents/setup` adds the repo-managed toolchain shims to `PATH`.
- Run repo tool commands directly, such as `pnpm test`.
- Use tmux session `dev` for long-lived/background work; create a new window per task.
- If `dev` is missing, create it with `tmux new-session -d -s dev -c /home/user/workspace/repo`, then open a new window with `tmux new-window -t dev -c /home/user/workspace/repo`.
- Reuse tmux session `dev` instead of creating extra detached process managers.
- The local `amp` database is pre-seeded with dev users, including `thorsten@ampcode.com` and `quinn@ampcode.com`. Sign in as one via dev magic-login: `https://localhost:2000/__dev/log-me-in/<email>?returnTo=/`.
- Save visual artifacts (screenshots, recordings, and similar media) under `.amp/in/artifacts/`.
EOF

After Amp runs .agents/setup it snapshots the sandbox and reuses that snapshot for up to 24 hours for new orbs. That speeds things up.

.agents/resume

Orbs go to sleep when you or the agents no longer need them. They wake up as soon as there’s work to do again.

.agents/resume runs on every wake-up and is a chance to make sure everything in the orb is in the right state.

Our .agents/resume right now only contains a single script invocation to re-establish networking connections, for an upcoming feature we’re working on.

A Dev Server for Agents

The central piece in our development environment is the dev server: it runs the development version of ampcode.com and all the services that make up the distributed system that makes Amp agents run anywhere, controllable from everywhere.

We have put a lot of effort into making it legible to agents, so they can start, use, debug, and modify it.

It starts with a skill called dev-server that’s in our repository. It contains a single SKILL.md file and a single script called ensure-dev-server.sh. Here’s what the SKILL.md file says about that script:

This script will:

- Ensure repo-root `.env.local` exists
- Ensure required local secrets exist for:
  `AMP_API_KEY_SECRET`, `THREAD_ACTORS_SERVICE_SECRET`, `THREAD_ACTORS_WEBSOCKET_JWT_SECRET`
- Use existing server if healthy (no restart)
- Kill and restart if busted (listening but not responding)
- Restart a healthy server when preflight updated env values
- Start fresh if nothing running
- Fail with clear error if run from wrong directory
- Use shared generated port metadata from `.amp/dev-ports.json`

Use the URLs from the output.

In other words: the script can reuse a healthy, already running server, or restart a wedged one, or start a fresh one if nothing’s running. The agent never has to figure out what state the server is in. Just run that script and you’re good to go.

Once the dev server is up, it writes into .amp/dev-ports.json every port it’s using — server, inference service, metrics. Other scripts and agents then read this file instead of a hardcoded localhost:2000 everywhere.

(This isn’t just handy for agents in orbs. With this script, multiple checkouts can start their own dev servers, derive their ports from a base PORT, and never collide.)

Authentication

Authentication has long been a pain in the orb for us and our agents. Secrets and credentials, OAuth, 2FA, redirects and cookies. No one was ever made happy when reading these words, but it’s especially sad when they stop your agent from using your dev server.

Our solution was to add /__dev endpoints.

These are endpoints that are only available in development mode (locally and in orbs) and are specifically made for agents:

  • /__dev lists the available endpoints.
  • /__dev/log-me-in/<email> signs the browser in as any local user.
  • /__dev/log-me-out signs the browser out.
  • /__dev/sudo starts a no-op passkey session for the current browser session, so we can get around passkey checks when testing remote control.
  • /__dev/preflight returns a JSON readiness report: are the secrets configured, is the server healthy, does the selected user have a workspace, a project, credits, an API key, can the CLI connect. When something fails, the agent curls preflight and gets told exactly what’s missing instead of guessing.

Instead of getting stuck and trying to wiggle its way out by creating new users or changing passwords, the agent now uses /__dev/log-me-in and can reliably get an authenticated session.

That was truly a game changer.

Logs

The dev server logs to .amp/in/server.log, but those logs also contain the browser’s console output, forwarded and tagged with [browser]. That gives the agent a single file it can grep to know what’s going on in a browser session.

Other services also log to .amp/in — we treat it as the scratch pad inbox for agents.

AGENTS.md

Our repository currently contains 41 AGENTS.md files that the agent will read on-demand when reading a file in a directory that contains one.

Here are some of them:

./labs/AGENTS.md
./infra/observability/AGENTS.md
./infra/AGENTS.md
./external-api/types/AGENTS.md
./core/AGENTS.md
./core/src/tools/builtin/AGENTS.md
./core/src/plugins/AGENTS.md
./core/src/skills/builtin/AGENTS.md
./server/migrations/AGENTS.md
./server/AGENTS.md
./server/src/lib/server/dev-preflight/AGENTS.md
./server/src/lib/db/AGENTS.md
./server/src/routes/(app)/storybook/AGENTS.md
./server/src/routes/(admin)/admin/AGENTS.md
./cli/AGENTS.md
./cli/src/tui/neo/AGENTS.md
./cli/src/tui/neo/widgets/AGENTS.md
./news/AGENTS.md
./sdk/AGENTS.md
./scripts/AGENTS.md
./lib/thread-client/AGENTS.md
./lib/thread-protocol/AGENTS.md
./AGENTS.md

These files tie everything together. If you were to read them all, you’d know what Amp is, what the different clients are and how they interact, where and how the server is deployed, which 3rd-party providers we use for what, what the code conventions are in which folders, what not to do, what nasty bugs we ran into and want to avoid in the future, and, most importantly for this post, how to build, run, modify, and test everything in the repository.

The root AGENTS.md truly is the root of it all. It contains information about code style and security guidelines, infrastructure and how to administer that, how we use Git or jujutsu, what to avoid in tests, what the most important folders are, which other AGENTS.md files to look at, and, yes, the development tooling:

  • List of all the build commands and how to use them.
  • Skill and scripts to use to run the dev server.
  • Location of logs and how they get written.
  • Ports being used by the dev server.
  • How to use the agent-browser skill and tool.
  • What storybooks are and how we use them, in the CLI and on the web.

Mental Model

I asked the agent from above, the one that ran through the Amp core flow and created and remote-controlled threads, what it’s like to work with this codebase in an orb.

Here’s what it wrote:

The thing that stands out is how rarely I have to guess. “Start the dev server, log in as this user, create a thread with the CLI, drive it from the web UI” — every step had a paved path: one script that puts the dev server into a known-good state, a JSON file with the ports, a magic-login URL instead of an OAuth maze. When the user I needed didn’t exist, the guidance told me which tables to seed instead of leaving me to retry failed logins.

And my errors get cheap. When a browser screenshot came back blank, the logs were one grep away and the skill docs had already anticipated my exact failure. Setup, dev server, seeds — all idempotent, and the orb is disposable anyway. So I act, check, and correct instead of over-planning around mistakes I can’t observe. The environment doesn’t just tolerate an agent; it assumes one, and tells it where the light switches are.

I think that’s a great summary of the things we’ve done to make agents more productive in our codebase: don’t make them guess.