Ralph Loop | Ralph Loop Blog

How to Run a Ralph Loop With the Cursor CLI

Mon, 29 Jun 2026 00:00:00 GMT

To run a Ralph loop with the Cursor CLI, install Ralph into your project, create a task list, log in to Cursor once inside its sandbox, then run ./ralph.sh --agent cursor. Ralph wraps the headless cursor-agent in print mode, gives it a fresh context window every iteration, and keeps re-running it against your task list until the work is done or you hit the iteration cap.

This is the full setup walkthrough, from an empty repo to a finished diff. If you are new to the loop itself, start with what the Ralph technique is. If you want the flag-level mechanics of the Cursor backend, the companion piece is running the Cursor CLI agent in a loop. This post is the end-to-end recipe.

Why pair Ralph with the Cursor CLI?

Cursor ships a headless agent, cursor-agent, that runs from the terminal with no editor attached. In print mode (-p) it reads a prompt, edits files, runs shell commands, prints a final message, and exits. That exit is the hook Ralph needs. Each iteration is a discrete unit: spawn the agent, let it do one task, read what it emitted, repeat.

Ralph supplies the three things a single cursor-agent call cannot:

A loop, so the agent gets another pass after every commit instead of stopping.
Fresh context per iteration, so a long run never rots into a confused, drifting session.
A Docker sandbox boundary, so the agent can edit files and run commands in YOLO mode without that blast radius reaching your real machine.

The state lives on disk (the task list, the logs, the git history), not in a chat transcript. That is what lets a stateless cursor-agent reorient on every pass and still make forward progress across dozens of iterations.

Step 1: Install Ralph

Run the installer in your project root. It drops the ralph.sh script and the .agent/ directory into the repo.

npx @pageai/ralph-loop

The installer asks for your dev server URL and port and your default agent, then writes a default implementation-mode setup. Pick cursor when prompted, or set it per run with --agent cursor later. After install, make the script executable if it is not already:

chmod +x ralph.sh

Ralph runs each agent inside a Docker Sandbox, so install and sign in to Docker Sandbox first. See the Docker Sandboxes docs for the official setup flow. The loop drives the standalone sbx CLI under the hood.

Step 2: Create a PRD and task list

The loop executes a task list. It does not invent one. Before you run anything, turn your requirements into a PRD and a set of task specs with the prd-creator skill.

Open Cursor (or any agent) in plan mode and prompt it with your requirements:

Use the prd-creator skill to help me create a PRD and task list for the below requirements.

An app is already set up with React, Tailwind CSS and TypeScript.

Requirements:
- A SaaS product that helps users manage their finances.
- Track income and expenses, create invoices, generate reports.
- Use shadcn/ui for components and Supabase for the database.
// etc.

The skill writes .agent/prd/PRD.md, a short .agent/prd/SUMMARY.md, and per-task specs under .agent/tasks/, indexed by .agent/tasks.json. Review each task individually before you start. A clear task list with real acceptance criteria is the single biggest factor in whether the loop succeeds. The deeper version of that workflow is in spec-driven development with AI.

Step 3: Log in to Cursor inside the sandbox

Cursor runs inside an isolated sandbox, not on your host, so it needs credentials in that environment. Authenticate once with the login action:

./ralph.sh --login --agent cursor

Ralph prints the login command for every supported agent, highlights the Cursor one, and drops you into the sandbox shell. The command it runs to create the box looks like this:

sbx run --name ralph-cursor-<project>-<hash8> cursor .

Inside the sandbox, authenticate Cursor once. Run cursor-agent login and follow the prompt, or set a CURSOR_API_KEY environment variable. Confirm the session with cursor-agent status. The credential persists in that named sandbox, so later runs attach to the same box already logged in.

Each agent gets its own deterministic sandbox name, built from the agent slug, the project directory, and an 8-character hash of the absolute path:

ralph-cursor-<project>-<hash8>

Print the exact name for your project without starting a run:

./ralph.sh --print-name --agent cursor

If your tasks run a dev server you want to reach from the host, publish the configured port to the Cursor sandbox. The port comes from the dev-server URL you set during install:

./ralph.sh --ports --agent cursor

That expands to an sbx ports call against the Cursor sandbox, for example sbx ports ralph-cursor-<project>-<hash8> --publish 3000:3000. Per-agent names keep state separate: your Cursor sandbox and your Claude sandbox never share credentials or installed tools, so you can run both against the same repo without one clobbering the other.

Step 4: Run the loop with Cursor

With a task list in place and Cursor authenticated, start the loop. The default agent is Claude, so name Cursor explicitly:

# 10 iterations (the default)
./ralph.sh --agent cursor

# 50 iterations for a longer unattended run
./ralph.sh --agent cursor -n 50

# exactly one iteration, good for a smoke test
./ralph.sh --agent cursor --once

The short form -a works too: ./ralph.sh -a cursor -n 5. The iteration count is a safety budget, not a target. The loop stops the moment the work is done.

Under the hood, Ralph builds a cursor-agent command and runs it inside the sandbox. For ./ralph.sh --agent cursor, the expansion is:

sbx run --name ralph-cursor-<project>-<hash8> cursor . -- -p "$PROMPT_CONTENT"

The -p flag is Cursor’s print (headless) mode, which still has full tool access including file writes and shell. That is exactly what a loop needs: an agent that can do real work without a person approving each step.

Pass a model and flags after the separator

Everything to the right of Ralph’s own -- separator is forwarded straight to cursor-agent, inserted right after -p. So this:

./ralph.sh --agent cursor -- --model auto

expands to:

sbx run --name ralph-cursor-<project>-<hash8> cursor . -- -p --model auto "$PROMPT_CONTENT"

Do not guess at model names. Run cursor-agent models inside the sandbox to print the exact identifiers Cursor accepts, then pass one. The rule to remember: everything left of -- configures Ralph (agent, iteration count, login), and everything right of -- configures Cursor. A practical full command for an overnight run:

./ralph.sh --agent cursor -n 50 -- --model auto --force

The --force flag (alias --yolo) lets Cursor run commands without pausing for approval, which is what keeps an unattended run from stalling on a prompt nobody is there to answer. It is safe here only because the sandbox is the boundary.

What happens each iteration

Every pass is mechanical and identical. The agent reorients from disk, does one task, proves it works, and commits.

Find the highest-priority incomplete task in .agent/tasks.json.
Work the steps in .agent/tasks/TASK-{ID}.json.
Run tests, linting, and type checking.
Complete the task, take a screenshot, update the task status, and commit.
Repeat until all tasks pass or the iteration cap is reached.

The key detail is that each iteration spawns a fresh cursor-agent -p with a clean context window. The agent does not carry an hours-long transcript from one task to the next. It reads the current state from disk, does one task, and exits. This is why the loop deliberately does not use Cursor’s own session resume flags: continuity is a liability here, not a feature.

flowchart TD
    Start(["./ralph.sh --agent cursor -n 50"]) --> Pick["Pick top task from .agent/tasks.json"]
    Pick --> Spawn["sbx run cursor . -- -p (fresh context)"]
    Spawn --> Work["cursor-agent reads state, edits files, runs commands"]
    Work --> Verify["Run tests, lint, type check, screenshot"]
    Verify --> Commit["Commit and update task status"]
    Commit --> Check{"Promise tag emitted?"}
    Check -->|"none"| Pick
    Check -->|"COMPLETE"| Done(["exit 0, all tasks done"])
    Check -->|"BLOCKED or DECIDE"| Stop(["exit 2 or 3, wants a human"])

The filesystem and git history are the memory layer. Progress lives in .agent/tasks.json, .agent/logs/LOG.md, the per-task specs, and the git log, not in a chat transcript. The prompt that drives every pass lives in .agent/PROMPT.md, and writing it well is its own skill, covered in how to write the PROMPT.md file.

One rule keeps the whole thing reliable: one task per invocation. Cursor completes exactly one task, commits, and stops. It never batches several tasks into a single iteration, which is what keeps each commit small and each diff reviewable.

How the loop knows when to stop

A loop that never ends is a money fire, so Ralph stops on an explicit signal rather than a guess. Cursor emits a semantic promise tag in its final message and Ralph reads it:

<promise>COMPLETE</promise> means every task is finished.
<promise>BLOCKED:reason</promise> means the agent needs human help.
<promise>DECIDE:question</promise> means it needs a decision you have to make.

Those map to exit codes, which is what makes the loop scriptable:

./ralph.sh --agent cursor -n 50
echo $?   # 0 COMPLETE, 1 MAX_ITERATIONS, 2 BLOCKED, 3 DECIDE

Exit code 1 is not a failure. It means the loop spent its iteration budget with work still pending, which is exactly what a safety cap is for. The full design lives in completion promises and exit codes. If Cursor is not authenticated when the loop starts, Ralph detects the auth failure, stops, and tells you to run ./ralph.sh --login --agent cursor, so it never thrashes on a box that can never make progress.

Steer, debug, and review

Three things keep a long Cursor run under control.

Steer without stopping

If you notice the agent heading the wrong way, you do not have to kill the loop. Edit .agent/STEERING.md while it runs. The agent checks that file on each pass and handles the critical work there before resuming the normal task order. That is steering, not stopping, and it keeps momentum while you correct course.

Get inside the sandbox

The sandbox is a normal container you can poke at. List what exists, then open a shell in the Cursor box:

sbx ls
sbx exec -it ralph-cursor-<project>-<hash8> bash

From there you can re-run a failing test by hand, confirm auth with cursor-agent status, or read .agent/logs/LOG.md and the per-iteration logs in .agent/history/. When an install fails, the deny-by-default network is usually the cause. Allow the domain it needs:

sbx policy allow network ralph-cursor-<project>-<hash8> registry.npmjs.org

That is a feature, not a bug. The agent installs what the task needs without a path to exfiltrate your source. The full argument is in running AI coding agents in Docker sandboxes safely.

Review the diff in the morning

Because every task is committed separately, the morning review is a git review, not an archaeology dig:

git log --oneline
git diff main...HEAD

You read the commits in order, eyeball the screenshots the agent captured, and accept or revert. A single bad task is one revert, not a tangled mess. This is the whole premise of running an AI coding agent overnight.

Should you use Cursor or another agent?

Ralph is agent agnostic. The supported agents are claude (default), codex, copilot, cursor, gemini, and opencode, and switching is a single flag. Cursor is a strong default when you already pay for it and want its model routing through --model auto. The loop machinery is identical across agents, so the choice comes down to which CLI holds up over a multi-hour run. That comparison is in the best agentic CLI for long-running tasks, and the broader field guide is agentic coding CLIs.

A real Cursor loop, start to finish, is four commands:

# 1. install Ralph and scaffolding
npx @pageai/ralph-loop

# 2. authenticate once (creates the sandbox, you log in inside it)
./ralph.sh --login --agent cursor

# 3. smoke test a single pass
./ralph.sh --agent cursor --once

# 4. run the loop for real with a model and force mode
./ralph.sh --agent cursor -n 50 -- --model auto --force

Define your tasks in .agent/tasks.json, write a clear .agent/PROMPT.md, start the loop, and read the commits in the morning.

Frequently asked questions

How do I run a Ralph loop with the Cursor CLI?

Install Ralph with npx @pageai/ralph-loop, create a task list, log in with ./ralph.sh --login --agent cursor, then run ./ralph.sh --agent cursor. Ralph wraps the headless cursor-agent in print mode inside a Docker sandbox, starts a fresh context each iteration, and repeats until every task in .agent/tasks.json is done or the iteration cap is reached.

Does ralph.sh support the Cursor CLI?

Yes. Cursor is one of the supported agents, alongside claude, codex, copilot, gemini, and opencode. Select it with --agent cursor or the short form -a cursor. Ralph builds a cursor-agent command and runs it inside a deterministic sandbox named ralph-cursor-<project>-<hash8>.

How do I pass a Cursor model through Ralph?

Put it after the -- separator. Anything to the right of -- is forwarded to cursor-agent, so ./ralph.sh --agent cursor -- --model auto runs cursor-agent in print mode with that model and the Ralph prompt. Run cursor-agent models inside the sandbox to list the exact identifiers Cursor accepts.

How do I log in to Cursor for the loop?

Run ./ralph.sh --login --agent cursor. It drops you into the sandbox shell where you run cursor-agent login, or you can set CURSOR_API_KEY. The credential persists in that named sandbox, so future runs attach to the same box already authenticated.

Is it safe to run cursor-agent in force or YOLO mode?

It is unsafe on your laptop and reasonable inside a sandbox. Ralph runs cursor-agent in an isolated Docker Sandbox microVM with network denied by default, so --force lets the agent run commands without approval prompts while staying unable to touch your real files. The sandbox is the boundary, not the agent.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

The Ralph Loop Shell Script: How ralph.sh Works and How to Run It

Sun, 28 Jun 2026 00:00:00 GMT

The Ralph loop shell script is ralph.sh, a single Bash file that runs an AI coding agent in a loop until your task list is done. It is open source. You can read the docs at ralphloop.sh and the full source at github.com/pageai-pro/ralph-loop. You install it into a project with one command, point it at a task list, and let it grind.

This post is about the script itself. What it is, how to get it, the flags that drive it, what it does on each pass, and why it is a shell script you can read top to bottom instead of a framework you have to trust. If you want the concept behind it first, read what the Ralph technique is and come back.

What is the Ralph loop shell script?

ralph.sh is the practical implementation of the Ralph technique. The technique was popularized by Geoffrey Huntley with one line: Ralph is a Bash loop. The script keeps that idea and adds the parts a real run needs: a task system, a verification gate, a stop condition, a choice of agent backends, and a sandbox boundary.

The whole thing stays a shell script on purpose. There is no orchestration layer, no daemon, no hidden state. When the loop does something you did not expect, you open one file and read it. That is the trade the project makes, and it is the reason the script exists at all when an official Claude Code plugin already does a similar job.

Here is the mental model in two layers. The bare idea is a loop that pipes a prompt into an agent. The script wraps that idea with the machinery that makes it safe to walk away from.

# the bare idea
while :; do
  cat PROMPT.md | your-agent-cli
done

# the real script, in one line
./ralph.sh -n 50

Both feed the same prompt to a fresh agent on every pass. The difference is everything the second line does around that: caps the iterations, isolates the run, tracks tasks, and stops on a real signal.

How do you get the ralph.sh script?

Run one command in your project’s root. It scaffolds the .agent/ directory and drops ralph.sh into the repo.

npx @pageai/ralph-loop

The installer asks a few questions (your dev server URL and port, your agent of choice) and writes a default implementation-mode setup. After that the script lives in your repo as a normal file. You can read it, edit it, and commit it alongside the rest of your code.

If the file is not executable yet, make it so:

chmod +x ralph.sh

That is the entire install. No global binary, no background service. The script and its state files sit in your project, version controlled like anything else.

How do you run the Ralph loop script?

The script takes a small set of flags. The defaults are sane, so the shortest run is just the script with no arguments, which runs ten iterations.

# default: 10 iterations
./ralph.sh

# set an explicit cap (these are equivalent)
./ralph.sh 50
./ralph.sh -n 50
./ralph.sh --max-iterations 50

# run exactly one iteration to sanity check the setup
./ralph.sh --once

The iteration cap is a safety budget, not a target. The loop stops early the moment the work is actually done. The cap only matters if the agent runs out of budget before finishing, which is a signal to read the log and decide whether to top it up.

Choosing an agent

The script is agent agnostic. Claude Code is the default. Switch to another supported CLI with --agent or its short form -a.

./ralph.sh --agent codex
./ralph.sh -a cursor -n 5

Supported agents are claude, codex, copilot, cursor, gemini, and opencode. To pass flags straight through to the underlying agent, put them after a -- separator so the script does not try to parse them:

./ralph.sh --agent codex -- --model gpt-5.5
./ralph.sh -a gemini -- --model pro

Auth, ports, and the sandbox name

Three more flags handle setup around the sandbox. Authenticate the agent inside its sandbox, publish your dev port to the host, or print the deterministic sandbox name without starting a run.

./ralph.sh --login
./ralph.sh --login --agent cursor

./ralph.sh --ports

./ralph.sh --print-name
./ralph.sh --print-name --agent codex

The sandbox name follows the pattern ralph-<agent>-<current-dir>-<hash8>, for example ralph-claude-my-app-a1b2c3d4. Because the agent name is part of the sandbox name, switching agents gives each one its own sandbox for the same project.

What does the script do on each iteration?

Every pass follows the same shape. The agent boots with a clean context, reorients from files on disk, does exactly one task, proves it works, and commits. Then the loop runs the agent again.

flowchart TD
    Start(["./ralph.sh -n 50"]) --> Read["Read .agent/tasks.json"]
    Read --> Pick{"Incomplete task left?"}
    Pick -->|"No"| Done["Emit COMPLETE, exit 0"]
    Pick -->|"Yes"| Fresh["Spawn agent with fresh context in the sandbox"]
    Fresh --> Spec["Load TASK-ID.json steps"]
    Spec --> Work["Implement the one task"]
    Work --> Verify["Run tests, lint, typecheck"]
    Verify --> Pass{"All checks pass?"}
    Pass -->|"No"| Work
    Pass -->|"Yes"| Commit["Screenshot, set passes:true, commit"]
    Commit --> Limit{"Max iterations reached?"}
    Limit -->|"No"| Read
    Limit -->|"Yes"| MaxOut["Exit 1"]

In words, the five steps are:

Find the highest-priority incomplete task in .agent/tasks.json.
Work the steps in .agent/tasks/TASK-{ID}.json.
Run tests, linting, and type checking.
Complete the task, take a screenshot, update the task status, and commit.
Repeat until every task passes or the iteration cap is reached.

The verification step in the middle is what makes the loop worth trusting. The agent does not get to call a task done on a vibe. The repo assumes a stack of Playwright for end to end tests, Vitest for unit tests, TypeScript for types, ESLint for linting, and Prettier for formatting. The mantra from the repo is blunt: if you didn’t test it, it doesn’t work.

The prompt that drives every pass lives in .agent/PROMPT.md. The script re-sends that same file on each iteration, so the prompt has to make a fresh agent reorient and act within seconds. Writing it well is its own skill, covered in how to write the PROMPT.md file.

What lives next to the script?

ralph.sh reads and writes a small set of files under .agent/. The script is the engine; these files are its memory. A fresh agent remembers nothing between passes, so progress has to live on disk.

.agent/
├── PROMPT.md           # Prompt sent to the agent each iteration
├── tasks.json          # Task lookup table (required)
├── tasks/              # Individual task specs (TASK-{ID}.json)
├── prd/
│   ├── PRD.md          # Product requirements document
│   └── SUMMARY.md      # Short project overview sent each iteration
├── logs/
│   └── LOG.md          # Progress log
├── history/            # Per-iteration output logs
├── skills/             # Shared skills
└── STEERING.md         # Critical work injected mid-run

The task lookup table in tasks.json is a lightweight index. The agent reads it to pick the next task without loading every spec, which is what lets a project hold hundreds of tasks and still keep each iteration cheap. Each task has a detailed spec in tasks/TASK-{ID}.json with steps and acceptance criteria.

You can steer a run that is already going by editing .agent/STEERING.md. The agent checks that file on each pass and handles any critical work there before resuming the normal task order, so you can correct course without killing the loop.

Promise tags and exit codes

A loop that never ends is a money fire, so the script stops on explicit signals rather than guesses. There are two layers. The agent emits a promise tag, and the script returns an exit code.

The promise tags are small semantic statuses the agent prints:

<promise>COMPLETE</promise>         all tasks finished, exit the loop
<promise>BLOCKED:reason</promise>   needs human help
<promise>DECIDE:question</promise>  needs a decision

Those tags map to exit codes, which is what makes the script easy to wire into CI or a cron job:

./ralph.sh -n 50
echo $?   # 0 COMPLETE, 1 MAX_ITERATIONS, 2 BLOCKED, 3 DECIDE

Exit code 1 is not a failure. It means the loop spent its iteration budget with work still pending, which is exactly what a safety cap is for. You read the log, top up the budget, and run it again. The full design of how a loop knows it is done lives in completion promises and exit codes.

Why a shell script and not a framework?

Three reasons, and they all come back to control.

First, you can read it. A shell script you can review in one sitting is a script you can debug at 2 in the morning. When a run does something surprising, you open ralph.sh and trace exactly when it commits, how it caps iterations, how it names the sandbox, and how it reads the completion promise. That is much harder with a closed plugin.

Second, you can hack it. The script is meant to be edited. The default mode is implementation, but the behavior lives in .agent/PROMPT.md, so you can point the same loop at a refactor, a review, or a test backfill by editing one file. The script machinery does not change.

Third, it is honest about its dependencies. The verification stack, the agent CLI, the sandbox, all of it is visible in the script and the prompt. Nothing is doing work you cannot see. For the longer argument about why this beats firing one giant prompt and hoping, read Ralph loop vs one-shot prompting, and for the origin of the one-liner the script grew from, see who invented the Ralph technique.

The sandbox boundary

The script runs each agent inside an isolated Docker Sandbox microVM using the standalone sbx CLI. That isolation is what lets the loop run in bypass-permissions mode, often called YOLO mode, without putting your real machine at risk. The sandbox is the boundary, not the agent’s good behavior. See the Docker Sandboxes docs for the isolation model.

If you need to look inside while a run is going, list the sandboxes and shell into the one you want:

sbx ls
sbx exec -it ralph-claude-my-app-a1b2c3d4 bash

From there you have a normal container shell. You can install packages, run commands, or start the agent CLI by hand to reproduce what the loop is doing.

A typical first run

Putting it together, the shortest path from nothing to a running loop is four commands. Install, create a task list, test one pass, then let it run.

# 1. install the script and scaffolding
npx @pageai/ralph-loop

# 2. (in your editor, plan mode) use the prd-creator skill to turn
#    requirements into .agent/prd/PRD.md and task specs

# 3. confirm the setup works end to end
./ralph.sh --once

# 4. let it run for a real batch
./ralph.sh -n 50

The quality of step 2 decides almost everything. The script executes a task list well, but it does not write the task list for you. A vague task list produces a loop that thrashes. A clear one with acceptance criteria produces commits you can trust. Once the script is working, keeping it productive across a long unattended run is its own discipline, covered in how to run an AI coding agent overnight.

Frequently asked questions

What is the Ralph loop shell script?

It is ralph.sh, a single Bash file that runs an AI coding agent in a loop until your task list is done. It implements the Ralph technique with a task system, a verification gate, completion promises, a choice of agent backends, and a Docker sandbox. The source is open at github.com/pageai-pro/ralph-loop and the docs are at ralphloop.sh.

How do I install ralph.sh?

Run npx @pageai/ralph-loop in your project root. It scaffolds the .agent directory and drops ralph.sh into the repo with a default implementation-mode setup. If the file is not executable, run chmod +x ralph.sh. The script and its state files are version controlled like the rest of your code.

How do I run the Ralph loop script?

Run ./ralph.sh for the default ten iterations, or ./ralph.sh -n 50 to set a cap. Use ./ralph.sh --once to run a single pass. Choose an agent with --agent (claude, codex, copilot, cursor, gemini, or opencode) and pass agent flags after a -- separator.

Is ralph.sh just a while loop?

At its core it is the same idea as a shell while loop that feeds a prompt to a fresh agent each pass. The script adds the parts a real run needs: an iteration cap, a task lookup table, a verification gate, promise tags, exit codes, and a sandbox boundary. You can still read the whole thing as a single shell file.

Can I edit the script for my own stack?

Yes, that is the point. The script is hackable and the loop behavior lives in .agent/PROMPT.md, so you change what the loop does by editing the prompt rather than the script. You can also adjust the verification commands, ports, and startup commands in the prompt to match your language and framework.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

How to Run a Ralph Loop With Claude Code

Fri, 26 Jun 2026 00:00:00 GMT

A ralph loop with Claude Code is the default path: install Ralph, log in to Claude once inside its sandbox, then run ./ralph.sh with no agent flag at all. Claude Code is Ralph’s default agent, so the bare command already wraps claude in headless print mode, hands it a fresh context window every iteration, and keeps re-running it against your task list until the work is done or you hit the iteration cap.

Claude is also the only agent whose output Ralph fully parses. That one fact is why the default is the default, and it changes what you see on screen while a run is happening. This post is the end-to-end setup walkthrough, from an empty repo to a reviewable diff. If the loop itself is new to you, read what the Ralph technique is first. If you want the flag-level mechanics of driving Claude in a loop, the companion piece is running Claude Code in a loop. Consider this the brand recipe and that one the mechanics deep dive.

The differentiator: Claude gives Ralph the richest live telemetry

Every supported agent runs the same loop. Only Claude streams structured JSON back that Ralph can read line by line.

Look at scripts/lib/agents.sh. The helper agent_uses_stream_json() returns success for exactly one agent:

agent_uses_stream_json() {
  [ "$1" = "claude" ]
}

And build_agent_command() emits Claude with two extra flags no other agent gets:

sbx run --name ralph-claude-<project>-<hash8> claude . -- --output-format stream-json --verbose -p "$PROMPT_CONTENT"

The --output-format stream-json --verbose pair turns Claude’s run into a stream of JSON events instead of an opaque wall of text. Ralph consumes that stream to power its live step detection (Thinking, Implementing, Testing) and the rolling preview of what the agent is doing right now. With Codex, Cursor, Copilot, Gemini, or OpenCode you still get a working loop, commits, and history logs, but you do not get the same real-time read on the agent’s internal state. If you want to watch a long unattended run and actually know what phase it is in, Claude is the agent with the most to say.

That is the practical case for the default. Not model quality (pick whatever your account supports), but observability. Ralph was built around Claude’s stream first, and everything else is a good citizen on top of the same machinery.

Two ways to loop Claude: the Stop Hook plugin vs the hackable script

Anthropic shipped an official way to loop Claude Code: a plugin that registers a Stop Hook, which fires when Claude finishes and re-injects the prompt so it keeps going. It lives in the Claude Code docs, and it is a clean, in-process way to keep a single Claude session churning.

Ralph takes the other road. Instead of a hook that resumes the same session, ralph.sh is a Bash loop that spawns a brand new claude process every iteration inside a Docker sandbox, with a clean context window each time. This is the original shape of the technique, popularized in Geoffrey Huntley’s Ralph writeup, where “Ralph is a Bash loop” is the whole point.

The trade-off is deliberate:

The Stop Hook keeps one session alive and re-prompts it. Continuity is the feature.
ralph.sh throws the session away and rebuilds state from disk. Discarding continuity is the feature, because it kills context rot on long runs.

Ralph’s script is also yours to edit. The verification stack, the sandbox boundary, the prompt, the step detection, all of it is in a shell script you can read and change. If you want the shape of the wrapper itself, that is covered in the Ralph loop shell script.

Step 1: Install Ralph

Run the installer in your project root. It writes the ralph.sh script and the .agent/ directory into the repo.

npx @pageai/ralph-loop

The installer asks for your dev server URL and port and your default agent. Claude is the sensible pick here, and it is already the fallback if you skip the choice. After install, make the script executable if it is not already:

chmod +x ralph.sh

Ralph runs each agent inside a Docker Sandbox, so install and sign in to Docker Sandboxes first. The Docker Sandboxes docs cover the official setup. Under the hood Ralph drives the standalone sbx CLI.

Step 2: Create a PRD and task list

The loop runs a task list. It does not invent one for you. Turn your requirements into a PRD and a set of task specs with the prd-creator skill before you run anything.

Open Claude Code (or any agent) in plan mode and prompt it:

Use the prd-creator skill to help me create a PRD and task list for the below requirements.

An app is already set up with React, Tailwind CSS and TypeScript.

Requirements:
- A SaaS product that helps users manage their finances.
- Track income and expenses, create invoices, generate reports.
- Use shadcn/ui for components and Supabase for the database.
// etc.

Step 3: Log in to Claude inside the sandbox

Claude runs inside an isolated sandbox, not on your host, so it needs credentials in that environment. Authenticate once with the login action. Claude is the default, so you can drop the agent flag, but naming it keeps things explicit:

./ralph.sh --login --agent claude

Ralph prints the login command for every supported agent, highlights the Claude one, and drops you into the sandbox shell. The command it runs to create the box looks like this:

sbx run --name ralph-claude-<project>-<hash8> claude .

Inside the sandbox, authenticate Claude once and follow the prompt. If OAuth login does not persist, the fallback is an API key: Docker Sandboxes forward environment variables at creation time, so you can set ANTHROPIC_API_KEY in your shell before recreating the box. When Claude is not authenticated at the start of a run, Ralph detects the failure and tells you to run /login, so it never burns iterations on a box that can never make progress.

Each agent gets its own deterministic sandbox name, built from the agent slug, the project directory, and an 8-character hash of the absolute path:

ralph-claude-<project>-<hash8>

Print the exact name for your project without starting a run:

./ralph.sh --print-name --agent claude

If your tasks run a dev server you want to reach from the host, publish the configured port to the Claude sandbox. The port comes from the dev-server URL you set during install:

./ralph.sh --ports --agent claude

Per-agent names keep state separate. Your Claude sandbox and, say, your Cursor sandbox never share credentials or installed tools, so you can run both against the same repo without one clobbering the other. If you later want the Cursor variant, that walkthrough is running a Ralph loop with the Cursor CLI.

Step 4: Run the loop with Claude

With a task list in place and Claude authenticated, start the loop. Because Claude is the default, the bare command already runs it:

# 10 iterations (the default), Claude by default
./ralph.sh

# the same thing, stated explicitly
./ralph.sh --agent claude

# 50 iterations for a longer unattended run
./ralph.sh -n 50

# exactly one iteration, good for a smoke test
./ralph.sh --once

The iteration count is a safety budget, not a target. The loop stops the moment the work is done. The short form -a works too, and --max-iterations 5 is a synonym for -n 5.

Under the hood, Ralph builds a claude command and runs it inside the sandbox. For a first run that creates the box, the expansion is:

sbx run --name ralph-claude-<project>-<hash8> claude . -- --output-format stream-json --verbose -p "$PROMPT_CONTENT"

The -p flag is Claude’s print (headless) mode, which still has full tool access including file writes and shell. The --output-format stream-json --verbose pair is Claude-only, and it is what feeds Ralph’s live preview.

Pass a model and flags after the separator

Everything to the right of Ralph’s own -- separator is forwarded straight to Claude, inserted between --verbose and -p. So this:

./ralph.sh --agent claude -- --permission-mode bypassPermissions

expands to:

sbx run --name ralph-claude-<project>-<hash8> claude . -- --output-format stream-json --verbose --permission-mode bypassPermissions -p "$PROMPT_CONTENT"

The rule to remember: everything left of -- configures Ralph (agent, iteration count, login), and everything right of -- configures Claude. If you want to pin a model, pass one your Anthropic account supports rather than guessing at an identifier. Do not hardcode a model name you are not sure exists.

YOLO mode is safe because the sandbox is the boundary

For a loop to run unattended it cannot pause for a human to approve each tool call. Claude Code has two ways to skip those prompts: --dangerously-skip-permissions, or the equivalent --permission-mode bypassPermissions. On your laptop that flag is genuinely reckless. Inside a Docker Sandbox it is the intended setup.

The sandbox is an isolated microVM with network denied by default. Claude can edit files and run shell commands freely inside it, but that blast radius never reaches your real machine. When the Docker Sandboxes login flow asks whether to bypass permissions, answering yes is exactly why you are running in a sandbox in the first place.

What happens each iteration

Every pass is mechanical and identical. Claude reorients from disk, does one task, proves it works, and commits.

Find the highest-priority incomplete task in .agent/tasks.json.
Work the steps in .agent/tasks/TASK-{ID}.json.
Run tests, linting, and type checking.
Complete the task, take a screenshot, update the task status, and commit.
Repeat until all tasks pass or the iteration cap is reached.

The key detail is that each iteration spawns a fresh claude -p with a clean context window. Claude does not carry an hours-long transcript from one task to the next. It reads the current state from disk, does one task, and exits. That is why the loop does not resume a prior Claude session: continuity is a liability here, not a feature.

flowchart TD
    Start(["./ralph.sh -n 50 (Claude default)"]) --> Pick["Pick top task from .agent/tasks.json"]
    Pick --> Spawn["sbx run claude . -- stream-json (fresh context)"]
    Spawn --> Stream["Ralph parses stream-json: Thinking, Implementing, Testing"]
    Stream --> Verify["Run tests, lint, type check, screenshot"]
    Verify --> Commit["Commit and update task status"]
    Commit --> Check{"Promise tag emitted?"}
    Check -->|"none"| Pick
    Check -->|"COMPLETE"| Done(["exit 0, all tasks done"])
    Check -->|"BLOCKED or DECIDE"| Stop(["exit 2 or 3, wants a human"])

The filesystem and git history are the memory layer. Progress lives in .agent/tasks.json, .agent/logs/LOG.md, the per-task specs under .agent/tasks/, and the git log, not in a chat transcript. The prompt that drives every pass lives in .agent/PROMPT.md, alongside .agent/prd/SUMMARY.md, .agent/history/ per-iteration logs, and .agent/STEERING.md.

One rule keeps the whole thing reliable: one task per invocation. Claude completes exactly one task, commits, and stops. It never batches several tasks into a single iteration, which is what keeps each commit small and each diff reviewable.

How the loop knows when to stop

A loop that never ends is a money fire, so Ralph stops on an explicit signal rather than a guess. Claude emits a semantic promise tag in its final message and Ralph reads it out of the stream:

<promise>COMPLETE</promise> means every task is finished.
<promise>BLOCKED:reason</promise> means the agent needs human help.
<promise>DECIDE:question</promise> means it needs a decision you have to make.

Those map to exit codes, which is what makes the loop scriptable:

./ralph.sh -n 50
echo $?   # 0 COMPLETE, 1 MAX_ITERATIONS, 2 BLOCKED, 3 DECIDE

Exit code 1 is not a failure. It means the loop spent its iteration budget with work still pending, which is exactly what a safety cap is for. Because Claude’s output is fully parsed, Ralph can pick these tags and phase changes out of the live stream instead of grepping a final blob, which is the observability edge again.

Steer, debug, and review

Three things keep a long Claude run under control.

Steer without stopping

If you notice Claude heading the wrong way, you do not have to kill the loop. Edit .agent/STEERING.md while it runs. The agent checks that file on each pass and handles the critical work there before resuming the normal task order. That is steering, not stopping, and it keeps momentum while you correct course.

Get inside the sandbox

The sandbox is a normal container you can poke at. List what exists, then open a shell in the Claude box:

sbx ls
sbx exec -it ralph-claude-<project>-<hash8> bash

From there you can re-run a failing test by hand, check auth by running claude, or read .agent/logs/LOG.md and the per-iteration logs in .agent/history/. To reattach to an existing box, sbx run ralph-claude-<project>-<hash8> picks it back up without the create-only --name form.

When an install fails, the deny-by-default network is usually the cause. Allow the domain it needs:

sbx policy allow network ralph-claude-<project>-<hash8> registry.npmjs.org

That is a feature, not a bug. Claude installs what the task needs without a path to exfiltrate your source.

Review the diff in the morning

Because every task is committed separately, the morning review is a git review, not an archaeology dig:

git log --oneline
git diff main...HEAD

You read the commits in order, eyeball the screenshots the agent captured, and accept or revert. A single bad task is one revert, not a tangled mess. That whole premise is covered in running an AI coding agent overnight.

The full Claude recipe, start to finish

A real Claude loop is four commands:

# 1. install Ralph and scaffolding
npx @pageai/ralph-loop

# 2. authenticate once (creates the sandbox, you log in inside it)
./ralph.sh --login --agent claude

# 3. smoke test a single pass
./ralph.sh --once

# 4. run the loop for real (Claude is the default agent)
./ralph.sh -n 50

Define your tasks in .agent/tasks.json, write a clear .agent/PROMPT.md, start the loop, and read the commits in the morning. The verification stack it assumes is Playwright for e2e, Vitest for units, TypeScript for types, ESLint for lint, and Prettier for format, so the mantra holds: if you didn’t test it, it doesn’t work.

Frequently asked questions

How do I run a Ralph loop with Claude Code?

Install Ralph with npx @pageai/ralph-loop, create a task list, log in with ./ralph.sh --login --agent claude, then run ./ralph.sh. Claude Code is the default agent, so the bare command already wraps claude in headless print mode inside a Docker sandbox, starts a fresh context each iteration, and repeats until every task in .agent/tasks.json is done or the iteration cap is reached.

Why is Claude Code the default agent in Ralph?

Claude is the only agent whose output Ralph fully parses. Ralph runs Claude with --output-format stream-json --verbose, and it reads that structured stream to detect the current phase (Thinking, Implementing, Testing) and show a live preview. Other agents still loop, commit, and log correctly, but they do not give the same real-time read on what the agent is doing.

What is the difference between Ralph and the official Claude Code loop?

Anthropic ships a plugin that uses a Stop Hook to re-inject the prompt and keep one Claude session going, so continuity is the point. Ralph is a hackable Bash script that spawns a brand new claude process each iteration inside a Docker sandbox with a clean context window, which kills context rot on long runs and lets you edit the wrapper yourself.

How do I pass flags or a model to Claude through Ralph?

Put them after the -- separator. Anything to the right of -- is forwarded to Claude, inserted between --verbose and -p, so ./ralph.sh --agent claude -- --permission-mode bypassPermissions runs Claude in print mode with that flag and the Ralph prompt. Pass a model your Anthropic account supports rather than guessing an identifier.

Is it safe to run Claude with --dangerously-skip-permissions?

It is reckless on your laptop and reasonable inside a sandbox. Ralph runs Claude in an isolated Docker Sandbox microVM with network denied by default, so --dangerously-skip-permissions (or --permission-mode bypassPermissions) lets the agent act without approval prompts while staying unable to touch your real files. The sandbox is the boundary, not the agent.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

How to Run a Ralph Loop With the Codex CLI

Tue, 23 Jun 2026 00:00:00 GMT

The ralph loop Codex setup is four moves: install Ralph into your project, log in to Codex once inside its sandbox, then run ./ralph.sh --agent codex. Ralph drives Codex through its non-interactive exec subcommand, hands it a fresh context window every iteration, and keeps re-running it against your task list until the work is done or you hit the iteration cap.

This is the full walkthrough, from an empty repo to a diff you review in the morning. If the loop itself is new to you, start with what the Ralph technique is. If you want the flag-level mechanics of the Codex backend, the companion piece is running the Codex CLI in a loop. This post is the brand-specific setup recipe.

What makes Codex different inside a Ralph loop?

Codex is the one agent Ralph does not drive with a print flag. Claude and Cursor take a -p flag; Gemini and Copilot take -p after their separators; OpenCode gets a run subcommand. Codex gets exec, its non-interactive execution mode. You can see the exact shape in scripts/lib/agents.sh, where build_agent_command emits the Codex case as ... -- exec%s "$PROMPT_CONTENT".

That subcommand matters more than it looks. codex exec is the headless path: it reads a prompt, edits files, runs commands, prints a final message, and exits with a status code. No REPL, no approval prompt waiting on a human, no interactive session to resume. Exit is the whole contract, and exit is exactly what a loop needs. Each iteration spawns one codex exec, lets it finish one task, reads what it emitted, and starts the next pass clean.

Ralph supplies the three things a lone codex exec call cannot:

A loop, so Codex gets another pass after every commit instead of stopping.
Fresh context per iteration, so a long unattended run never rots into a confused, drifting session.
A Docker sandbox boundary, so Codex can edit files and run shell commands in bypass-permissions mode without that blast radius reaching your real machine.

The state lives on disk (the task list, the logs, the git history), not in a chat transcript. That is what lets a stateless codex exec reorient on every pass and still make forward progress across dozens of iterations.

Step 1: Install Ralph

Run the installer in your project root. It drops the ralph.sh script and the .agent/ directory into the repo.

npx @pageai/ralph-loop

The installer asks for your dev server URL and port and your default agent, then writes a default implementation-mode setup. Pick codex when prompted, or set it per run with --agent codex later. If the script is not already executable, fix that:

chmod +x ralph.sh

Ralph runs each agent inside a Docker Sandbox, so install and sign in to Docker Sandbox first. See the Docker Sandboxes docs for the official setup flow. The loop calls the standalone sbx CLI under the hood, and the sandbox is what makes bypass-permissions mode safe.

Step 2: Log in to Codex inside the sandbox

Codex runs inside an isolated sandbox, not on your host, so it needs credentials in that environment. Authenticate once with the login action:

./ralph.sh --login --agent codex

Ralph prints the login command for every supported agent, highlights the Codex one, and drops you into the sandbox shell. The command it runs to create the box looks like this:

sbx run --name ralph-codex-<project>-<hash8> codex .

Inside the sandbox, authenticate Codex once. Run codex login and follow the prompt to connect your OpenAI account. If OAuth does not persist in the sandbox, the alternative is an OPENAI_API_KEY environment variable, which Docker Sandboxes forward when you create the box. The credential persists in that named sandbox, so later runs attach to the same box already logged in.

Each agent gets its own deterministic sandbox name, built from the agent slug, the project directory, and an 8-character hash of the absolute path:

ralph-codex-<project>-<hash8>

Print the exact name for your project without starting a run:

./ralph.sh --print-name --agent codex

If your tasks run a dev server you want to reach from the host, publish the configured port to the Codex sandbox. The port comes from the dev-server URL you set during install:

./ralph.sh --ports --agent codex

That expands to an sbx ports call against the Codex sandbox, for example sbx ports ralph-codex-<project>-<hash8> --publish 3000:3000. Per-agent names keep state separate: your Codex sandbox and your Claude sandbox never share credentials or installed tools, so you can run both against the same repo without one clobbering the other.

Step 3: Create a PRD and task list

The loop executes a task list. It does not invent one. Before you run anything, turn your requirements into a PRD and a set of task specs with the prd-creator skill.

Open Codex (or any agent) in plan mode and prompt it with your requirements:

Use the prd-creator skill to help me create a PRD and task list for the below requirements.

An app is already set up with React, Tailwind CSS and TypeScript.

Requirements:
- A SaaS product that helps users manage their finances.
- Track income and expenses, create invoices, generate reports.
- Use shadcn/ui for components and Supabase for the database.
// etc.

Step 4: Run the ralph loop codex command

With a task list in place and Codex authenticated, start the loop. Claude is the default agent, so name Codex explicitly:

# 10 iterations (the default)
./ralph.sh --agent codex

# 50 iterations for a longer unattended run
./ralph.sh --agent codex -n 50

# exactly one iteration, good for a smoke test
./ralph.sh --agent codex --once

The short form -a works too: ./ralph.sh -a codex -n 5. You can also cap iterations with --max-iterations 5. The count is a safety budget, not a target. The loop stops the moment the work is done.

Under the hood, Ralph builds a codex exec command and runs it inside the sandbox. For ./ralph.sh --agent codex, the expansion is:

sbx run --name ralph-codex-<project>-<hash8> codex . -- exec "$PROMPT_CONTENT"

Read that right to left. "$PROMPT_CONTENT" is the contents of .agent/PROMPT.md, the instruction set for one pass. exec puts Codex in non-interactive mode. Everything before the second -- is the sandbox wrapper. That is the entire ralph loop codex command: one headless Codex run per iteration, no session state carried between passes.

Pick a model and reasoning effort

Model selection is where the Codex path earns its own section, because Codex is the CLI where Ralph documents real model flags. Everything to the right of Ralph’s own -- separator is forwarded straight to Codex, inserted right after exec. So this:

./ralph.sh --agent codex -- --model gpt-5.5

expands to:

sbx run --name ralph-codex-<project>-<hash8> codex . -- exec --model gpt-5.5 "$PROMPT_CONTENT"

And the codex-reasoning variant works the same way:

./ralph.sh --agent codex -- --model gpt-5.3-codex

which expands to:

sbx run --name ralph-codex-<project>-<hash8> codex . -- exec --model gpt-5.3-codex "$PROMPT_CONTENT"

The rule to remember: everything left of -- configures Ralph (agent, iteration count, login), and everything right of -- configures Codex, landing right after exec. Pick the model that fits the run. A heavier reasoning model is worth the token cost on a gnarly refactor where a wrong turn compounds across iterations. A faster model is fine for mechanical task lists where each step is well specified. A practical full command for an overnight run:

./ralph.sh --agent codex -n 50 -- --model gpt-5.3-codex

Do not guess at other model identifiers. Use the ones your account and CLI version actually expose, and confirm them inside the sandbox before committing to a long run. The two above (gpt-5.5 and gpt-5.3-codex) are the ones Ralph’s own docs show, so they are safe starting points.

What happens each iteration

Every pass is mechanical and identical. Codex reorients from disk, does one task, proves it works, and commits.

Find the highest-priority incomplete task in .agent/tasks.json.
Work the steps in .agent/tasks/TASK-{ID}.json.
Run tests, linting, and type checking.
Complete the task, take a screenshot, update the task status, and commit.
Repeat until all tasks pass or the iteration cap is reached.

The key detail is that each iteration spawns a fresh codex exec with a clean context window. Codex does not carry an hours-long transcript from one task to the next. It reads the current state from disk, does one task, and exits. This is why the loop deliberately does not resume a prior Codex session: continuity is a liability here, not a feature.

flowchart TD
    Start(["./ralph.sh --agent codex -n 50"]) --> Pick["Pick top task from .agent/tasks.json"]
    Pick --> Spawn["sbx run codex . -- exec (fresh context)"]
    Spawn --> Work["codex exec reads state, edits files, runs commands"]
    Work --> Verify["Run tests, lint, type check, screenshot"]
    Verify --> Commit["Commit and update task status"]
    Commit --> Check{"Promise tag emitted?"}
    Check -->|"none"| Pick
    Check -->|"COMPLETE"| Done(["exit 0, all tasks done"])
    Check -->|"BLOCKED or DECIDE"| Stop(["exit 2 or 3, wants a human"])

The filesystem and git history are the memory layer. Progress lives in .agent/tasks.json, .agent/logs/LOG.md, the per-task specs, and the git log, not in a chat transcript. The prompt that drives every pass lives in .agent/PROMPT.md, which defaults to implementation mode and can be swapped for refactor, review, or test mode.

One rule keeps the whole thing reliable: one task per invocation. Codex completes exactly one task, commits, and stops. It never batches several tasks into a single iteration, which is what keeps each commit small and each diff reviewable.

How the loop knows when to stop

A loop that never ends is a money fire, so Ralph stops on an explicit signal rather than a guess. Codex emits a semantic promise tag in its final message and Ralph reads it:

<promise>COMPLETE</promise> means every task is finished.
<promise>BLOCKED:reason</promise> means the agent needs human help.
<promise>DECIDE:question</promise> means it needs a decision you have to make.

Those map to exit codes, which is what makes the loop scriptable:

./ralph.sh --agent codex -n 50
echo $?   # 0 COMPLETE, 1 MAX_ITERATIONS, 2 BLOCKED, 3 DECIDE

Exit code 1 is not a failure. It means the loop spent its iteration budget with work still pending, which is exactly what a safety cap is for. If Codex is not authenticated when the loop starts, Ralph detects the auth failure, stops, and tells you to run codex login, so it never thrashes on a box that can never make progress.

Steer, debug, and review

Three things keep a long Codex run under control.

Steer without stopping

If you notice Codex heading the wrong way, you do not have to kill the loop. Edit .agent/STEERING.md while it runs. Codex checks that file on each pass and handles the critical work there before resuming the normal task order. That is steering, not stopping, and it keeps momentum while you correct course.

Get inside the sandbox

The sandbox is a normal container you can poke at. List what exists, then open a shell in the Codex box:

sbx ls
sbx exec -it ralph-codex-<project>-<hash8> bash

From there you can re-run a failing test by hand, run codex interactively to confirm auth, or read .agent/logs/LOG.md and the per-iteration logs in .agent/history/. To reattach to the running box directly, use sbx run ralph-codex-<project>-<hash8> with no agent slug and no path. When an install fails, the deny-by-default network is usually the cause. Allow the domain it needs:

sbx policy allow network ralph-codex-<project>-<hash8> registry.npmjs.org

That is a feature, not a bug. Codex installs what the task needs without a path to exfiltrate your source. If you want the broader argument for why the sandbox is the boundary, running an AI coding agent overnight covers the safety model end to end.

Review the diff in the morning

Because every task is committed separately, the morning review is a git review, not an archaeology dig:

git log --oneline
git diff main...HEAD

You read the commits in order, eyeball the screenshots Codex captured, and accept or revert. A single bad task is one revert, not a tangled mess. The verification stack Ralph assumes (Playwright for end-to-end, Vitest for unit tests, TypeScript for types, ESLint for lint, Prettier for format) is what gives each commit evidence behind it. The repo mantra holds: if you did not test it, it did not work.

Should you use Codex or another agent?

Ralph is agent agnostic. The supported agents are claude (default), codex, copilot, cursor, gemini, and opencode, and switching is a single flag. The loop machinery is identical across all of them. What sets Codex apart is the interface: it is the one agent Ralph drives through the exec subcommand rather than a print flag, and the one where model selection is a documented, first-class part of the command. If you already run OpenAI models and want explicit control over which model and how much reasoning each run gets, Codex is a natural fit. If you want the pure shell mechanics behind all of this, read how Ralph is a shell script, and for the Cursor equivalent of this walkthrough, see running a Ralph loop with the Cursor CLI.

A real Codex loop, start to finish, is four commands:

# 1. install Ralph and scaffolding
npx @pageai/ralph-loop

# 2. authenticate once (creates the sandbox, you log in inside it)
./ralph.sh --login --agent codex

# 3. smoke test a single pass
./ralph.sh --agent codex --once

# 4. run the loop for real with a model
./ralph.sh --agent codex -n 50 -- --model gpt-5.3-codex

Define your tasks in .agent/tasks.json, write a clear .agent/PROMPT.md, pick a model, start the loop, and read the commits in the morning. The Ralph technique itself, fresh context plus disk-backed memory plus an explicit stop signal, was popularized by Geoffrey Huntley in his original writeup, and Codex slots into it cleanly through one non-interactive subcommand.

Frequently asked questions

How do I run a Ralph loop with the Codex CLI?

Install Ralph with npx @pageai/ralph-loop, create a task list, log in with ./ralph.sh --login --agent codex, then run ./ralph.sh --agent codex. Ralph drives Codex through its non-interactive exec subcommand inside a Docker sandbox, starts a fresh context each iteration, and repeats until every task in .agent/tasks.json is done or the iteration cap is reached.

Why does Ralph use codex exec instead of a print flag?

exec is Codex CLI non-interactive mode. It reads a prompt, edits files, runs commands, prints a final message, and exits with a status code, with no REPL or approval prompt waiting on a human. In scripts/lib/agents.sh the Codex case expands to sbx run codex . -- exec "$PROMPT_CONTENT", which is the exact behavior a loop needs.

How do I pass a model to Codex through Ralph?

Put it after the -- separator. Anything to the right of -- is forwarded to Codex and inserted right after exec, so ./ralph.sh --agent codex -- --model gpt-5.5 runs codex exec with that model and the Ralph prompt. The docs also show ./ralph.sh --agent codex -- --model gpt-5.3-codex. Confirm the exact identifiers your account exposes before a long run.

How do I log in to Codex for the loop?

Run ./ralph.sh --login --agent codex. It drops you into the sandbox shell where you run codex login, or you can set an OPENAI_API_KEY environment variable that Docker Sandboxes forwards when the box is created. The credential persists in the sandbox named ralph-codex-<project>-<hash8>, so future runs attach already authenticated.

What does the ralph loop codex exit code mean?

Codex emits a promise tag that Ralph maps to an exit code: 0 for COMPLETE when all tasks finish, 1 for MAX_ITERATIONS when the budget runs out with work pending, 2 for BLOCKED when it needs help, and 3 for DECIDE when it needs a decision. Exit code 1 is not a failure, it just means the safety cap did its job.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

How to Run a Ralph Loop With the Gemini CLI

Sat, 20 Jun 2026 00:00:00 GMT

A ralph loop gemini cli setup is the cheapest way to keep an agent working for hours: install Ralph into your project, log in to Gemini once inside its sandbox, then run ./ralph.sh --agent gemini. Ralph feeds the Gemini CLI a fresh context every iteration and keeps re-running it against your task list until the work is done or the iteration cap runs out. The reason to reach for Gemini specifically is money. A long unattended run is not one prompt, it is dozens, and the per-iteration model cost compounds across every pass.

This is the full recipe, from an empty repo to a reviewed diff, with cost as the through line. If the loop itself is new to you, start with what the Ralph technique is. If you want the flag-level internals of the Gemini backend, the companion piece is running the Gemini CLI in a loop. This post is the branded, end-to-end setup.

Why the Gemini CLI is the economical pick for a long loop

Think about what a long run actually is. The loop does not spend one model call and stop. It spends one call per task, and it keeps going until the task list is empty. Run fifty iterations overnight and you paid for fifty separate agent sessions, each reading state, editing files, running tests, and writing a commit. That is the arithmetic that matters: total cost equals the per-iteration cost multiplied by the number of iterations you allow.

Two properties make the Gemini CLI attractive for that arithmetic.

First, context size. Each Ralph iteration starts the agent from a clean context window, so it re-reads the task spec, the summary, and the relevant files every single pass. A model with a large context window swallows that reorientation without truncating, which keeps each pass from thrashing on a half-loaded picture of the repo. Fresh context is the point of Ralph, and a roomy window makes fresh context cheap to fill.

Second, model choice you can actually name. Ralph forwards agent-specific flags after its own -- separator, and the project README documents ./ralph.sh -a gemini -- --model pro as a real example. So you get an explicit lever: run the standard model for routine tasks, and pass --model pro when a batch of tasks needs more reasoning. You decide where the money goes instead of hoping a router guesses right.

Put those together and the emphasis of this whole post falls out: cost and context over a long unattended run. The iteration cap is not just a safety rail against runaway loops, it is your budget dial. Set -n and you have set a hard ceiling on how many model calls the run can make before it stops on its own.

Cap iterations to cap spend

The iteration count is the single most important number for cost control, so treat it as a budget, not a target.

# 10 iterations (the default)
./ralph.sh --agent gemini

# a tight budget: exactly one pass, good for a smoke test
./ralph.sh --agent gemini --once

# a small capped batch
./ralph.sh --agent gemini --max-iterations 5

# a long overnight run with a firm ceiling
./ralph.sh --agent gemini -n 50

Every one of those numbers is a spending limit. --once buys exactly one model call. -n 50 says the run may cost at most fifty passes before Ralph exits on its own, whether or not the task list is finished. The loop also stops early the moment the work is genuinely done, so you often pay for fewer iterations than the cap allows. You never pay for more.

This is why exit code 1 is not a failure (more on codes below). It means the run spent its budget with work still pending, which is exactly what a ceiling is for. Raise the cap and continue tomorrow, or shrink the task list, but you were never at risk of an open-ended bill.

The short form -a works everywhere the long --agent does, so ./ralph.sh -a gemini -n 50 is the same run. Pick the number that matches how much you are willing to spend while you sleep, then walk away.

Install Ralph

Run the installer in your project root. It drops the ralph.sh script and the .agent/ directory into the repo.

npx @pageai/ralph-loop

The installer asks for your dev server URL and port and your default agent, then writes a default implementation-mode setup. Pick gemini when prompted, or set it per run with --agent gemini later. If the script is not executable yet, fix that:

chmod +x ralph.sh

Ralph runs each agent inside a Docker Sandbox, so install and sign in to Docker Sandboxes first. See the Docker Sandboxes docs for the official setup flow. The loop drives the standalone sbx CLI under the hood, and the sandbox is what lets Gemini edit files and run commands without that reach touching your real machine.

Create a PRD and task list

The loop executes a task list. It does not invent one. Before you run anything, turn your requirements into a PRD and a set of task specs with the prd-creator skill. This step is also a cost decision: a vague task list makes Gemini flail across extra iterations, and every wasted iteration is money.

Open any agent in plan mode and prompt it with your requirements:

Use the prd-creator skill to help me create a PRD and task list for the below requirements.

An app is already set up with React, Tailwind CSS and TypeScript.

Requirements:
- A SaaS product that helps users manage their finances.
- Track income and expenses, create invoices, generate reports.
- Use shadcn/ui for components and Supabase for the database.
// etc.

The skill writes .agent/prd/PRD.md, a short .agent/prd/SUMMARY.md, and per-task specs under .agent/tasks/, indexed by .agent/tasks.json. Review each task individually before you start. A clear task list with real acceptance criteria is the single biggest factor in whether the loop succeeds, and the fewer dead-end passes you buy. The deeper version of that workflow is in spec-driven development with AI.

Log in to Gemini inside the sandbox

Gemini runs inside an isolated sandbox, not on your host, so it needs credentials in that environment. Authenticate once with the login action:

./ralph.sh --login --agent gemini

Ralph prints the login command for every supported agent, highlights the Gemini one, and drops you into the sandbox shell. The command it runs to create the box looks like this:

sbx run --name ralph-gemini-<project>-<hash8> gemini .

Inside the sandbox, complete the Gemini sign-in flow and follow the prompt. If a run later fails on auth, Ralph surfaces a hint that points at gemini auth, which tells you the box has no valid session. The credential persists in that named sandbox, so later runs attach to the same box already logged in.

An API key is an alternative to interactive login, and it matters for cost math because Docker Sandboxes only forward environment variables when a sandbox is created. If you go the key route, delete the sandbox first, set your provider API key in your shell before recreating it, then run ./ralph.sh --login --agent gemini again so the fresh sandbox picks the value up. The README’s authentication section describes this create-time forwarding pattern in full. Interactive login is usually the simpler path.

Each agent gets its own deterministic sandbox name, built from the agent slug, the project directory, and an 8-character hash of the absolute path:

ralph-gemini-<project>-<hash8>

Print the exact name for your project without starting a run:

./ralph.sh --print-name --agent gemini

If your tasks run a dev server you want to reach from the host, publish the configured port to the Gemini sandbox. The port comes from the dev-server URL you set during install:

./ralph.sh --ports --agent gemini

That expands to an sbx ports call against the Gemini sandbox, for example sbx ports ralph-gemini-<project>-<hash8> --publish 3000:3000. Per-agent names keep state separate: your Gemini sandbox and your Claude sandbox never share credentials or installed tools, so you can trial Gemini on a repo without disturbing another agent’s box.

Run the loop with Gemini

With a task list in place and Gemini authenticated, start the loop. The default agent is Claude, so name Gemini explicitly:

./ralph.sh --agent gemini -n 50

Under the hood, Ralph builds a Gemini CLI command and runs it inside the sandbox. For a first run that creates the box, the expansion is:

sbx run --name ralph-gemini-<project>-<hash8> gemini . -- -p "$PROMPT_CONTENT"

The -p flag is Gemini’s non-interactive prompt mode, which still has full tool access including file writes and shell. That is exactly what a loop needs: an agent that can do real work without a person approving each step.

Pass the model after the separator

Everything to the right of Ralph’s own -- separator is forwarded straight to the Gemini CLI, and Ralph inserts those extra args right before -p. So the README example:

./ralph.sh -a gemini -- --model pro

expands to:

sbx run --name ralph-gemini-<project>-<hash8> gemini . -- --model pro -p "$PROMPT_CONTENT"

That ordering is the mechanism to remember: the flags you pass land before the prompt flag, so the Gemini CLI sees your model choice and then the prompt. --model pro is the model the README documents for Gemini, so it is a safe lever to pull when a run needs stronger reasoning. Do not guess at other identifiers. Reach for the standard model on cheap, mechanical tasks and reserve pro for the passes that earn it, because that split is where a long run’s cost is won or lost.

The rule of the separator holds in general: everything left of -- configures Ralph (agent, iteration count, login), and everything right of -- configures Gemini. A practical full command for an overnight run:

./ralph.sh --agent gemini -n 50 -- --model pro

What each iteration buys

Every pass is mechanical and identical. The agent reorients from disk, does one task, proves it works, and commits. One iteration is one unit of spend, so it helps to know exactly what that unit does.

Find the highest-priority incomplete task in .agent/tasks.json.
Work the steps in .agent/tasks/TASK-{ID}.json.
Run tests, linting, and type checking.
Complete the task, take a screenshot, update the task status, and commit.
Repeat until all tasks pass or the iteration cap is reached.

The key detail is that each iteration spawns a fresh Gemini process with a clean context window. The agent does not carry an hours-long transcript from one task to the next. It reads the current state from disk, does one task, and exits. This is why the loop deliberately does not reuse a running session: continuity is a liability here, not a feature, and a fresh window avoids paying to re-send a transcript that has drifted off the plot.

flowchart TD
    Start(["./ralph.sh --agent gemini -n 50"]) --> Budget{"Iterations left in budget?"}
    Budget -->|"no"| Cap(["exit 1, budget spent"])
    Budget -->|"yes"| Pick["Pick top task from .agent/tasks.json"]
    Pick --> Spawn["sbx run gemini . -- --model pro -p (fresh context)"]
    Spawn --> Work["Gemini reads state, edits files, runs commands"]
    Work --> Verify["Run tests, lint, type check, screenshot"]
    Verify --> Commit["Commit and update task status"]
    Commit --> Check{"Promise tag emitted?"}
    Check -->|"none"| Budget
    Check -->|"COMPLETE"| Done(["exit 0, all tasks done"])
    Check -->|"BLOCKED or DECIDE"| Stop(["exit 2 or 3, wants a human"])

One rule keeps the whole thing reliable and cheap: one task per invocation. Gemini completes exactly one task, commits, and stops. It never batches several tasks into a single pass, which keeps each commit small, each diff reviewable, and each unit of spend accountable to a single piece of work.

Stop signals: promises and exit codes

A loop that never ends is a money fire, so Ralph stops on an explicit signal rather than a guess. Gemini emits a semantic promise tag in its final message and Ralph reads it:

<promise>COMPLETE</promise> means every task is finished.
<promise>BLOCKED:reason</promise> means the agent needs human help.
<promise>DECIDE:question</promise> means it needs a decision you have to make.

Those map to exit codes, which is what makes the loop scriptable and its spend legible after the fact:

./ralph.sh --agent gemini -n 50
echo $?   # 0 COMPLETE, 1 MAX_ITERATIONS, 2 BLOCKED, 3 DECIDE

Exit code 1 means the loop spent its iteration budget with work still pending, which is the expected outcome of a firm cap, not a bug. Codes 2 and 3 mean Gemini stopped early and wants a human, so you did not burn the rest of the budget on a task the agent could not finish alone. The full design lives in completion promises and exit codes. If Gemini is not authenticated when the loop starts, Ralph detects the auth failure, stops, and points you back at ./ralph.sh --login --agent gemini, so it never thrashes (and never spends) on a box that can never make progress.

Steer, inspect, and review

Three habits keep a long Gemini run under control and keep you from paying twice for the same work.

Steer without stopping

If you notice the agent heading the wrong way, do not kill the loop and restart it, because a restart pays for a cold start again. Edit .agent/STEERING.md while it runs. The agent checks that file on each pass and handles the critical work there before resuming the normal task order. That is steering, not stopping, and it corrects course without wasting the budget you already committed.

Get inside the sandbox

The sandbox is a normal container you can poke at. List what exists, then open a shell in the Gemini box:

sbx ls
sbx exec -it ralph-gemini-<project>-<hash8> bash

From there you can re-run a failing test by hand, confirm the session is valid, or read .agent/logs/LOG.md and the per-iteration logs in .agent/history/. When an install fails, the deny-by-default network is usually the cause. Allow the domain it needs:

sbx policy allow network ralph-gemini-<project>-<hash8> registry.npmjs.org

That is a feature, not a limitation. The agent installs what the task needs without a path to exfiltrate your source. The full argument is in running AI coding agents in Docker sandboxes safely.

Review the diff in the morning

Because every task is committed separately, the morning review is a git review, not an archaeology dig:

git log --oneline
git diff main...HEAD

You read the commits in order, eyeball the screenshots the agent captured, and accept or revert. A single bad task is one revert, not a tangled mess, so a wasted iteration costs you one small commit rather than the whole night’s work. This is the whole premise of running an AI coding agent overnight, and the broader money discipline is in controlling AI agent cost.

Gemini or another agent?

Ralph is agent agnostic. The supported agents are claude (default), codex, copilot, cursor, gemini, and opencode, and switching is a single flag. The loop machinery is byte-for-byte identical across all of them, so the choice comes down to the economics of a multi-hour run: how much context each model can hold on a fresh start, and what each pass costs you. Gemini earns its place when you want a large context window and an explicit --model pro lever over a long, capped run. The shell-script guts that make the loop hackable are in the Ralph loop shell script, and the branded sibling recipe is running a Ralph loop with the Cursor CLI.

A real Gemini loop, start to finish, is four commands:

# 1. install Ralph and scaffolding
npx @pageai/ralph-loop

# 2. authenticate once (creates the sandbox, you log in inside it)
./ralph.sh --login --agent gemini

# 3. smoke test a single pass (one unit of spend)
./ralph.sh --agent gemini --once

# 4. run the loop for real with a model and a firm budget
./ralph.sh --agent gemini -n 50 -- --model pro

Define your tasks in .agent/tasks.json, write a clear .agent/PROMPT.md, set the iteration cap to a number you are comfortable paying for, start the loop, and read the commits in the morning. The Ralph technique itself traces back to Geoffrey Huntley’s original writeup, Ralph is a Bash loop, and everything above is that idea wired to the Gemini CLI inside a sandbox.

Frequently asked questions

How do I run a Ralph loop with the Gemini CLI?

Install Ralph with npx @pageai/ralph-loop, create a task list, log in with ./ralph.sh --login --agent gemini, then run ./ralph.sh --agent gemini. Ralph runs the Gemini CLI in non-interactive prompt mode inside a Docker sandbox, starts a fresh context each iteration, and repeats until every task in .agent/tasks.json is done or the iteration cap is reached.

Why choose Gemini for a long unattended loop?

Cost and context. A long run is many iterations, and the per-iteration model cost compounds across every pass, so the model you pick matters. Gemini offers a large context window that absorbs the fresh-context reorientation each iteration needs, and Ralph lets you name the model with --model pro when a batch of tasks needs stronger reasoning.

How do I control cost when looping Gemini?

Use the iteration cap as a budget. ./ralph.sh --agent gemini --once buys exactly one pass, -n 50 caps the run at fifty passes, and the loop still stops early when the work is done so you often pay for fewer. Exit code 1 means the budget was spent with work still pending, which is the cap doing its job.

How do I pass a Gemini model through Ralph?

Put it after the -- separator. Anything to the right of -- is forwarded to the Gemini CLI and inserted just before the prompt flag, so ./ralph.sh -a gemini -- --model pro expands to sbx run --name ralph-gemini-<project>-<hash8> gemini . -- --model pro -p with the Ralph prompt. --model pro is the model documented in the README.

How do I log in to Gemini for the loop?

Run ./ralph.sh --login --agent gemini. It creates the sandbox and drops you into its shell to complete the Gemini sign-in. If a run later fails on auth, Ralph points you back at gemini auth. As an alternative you can set your provider API key in your shell before recreating the sandbox, since Docker Sandboxes only forward environment variables at create time.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

How to Run a Ralph Loop With the GitHub Copilot CLI

Wed, 17 Jun 2026 00:00:00 GMT

A Ralph loop with Copilot runs the GitHub Copilot CLI on your task list in a fresh context every iteration, and the one detail that makes it different from every other agent is auth: Copilot signs in through the GitHub CLI (gh auth login), not an agent-specific login. Install Ralph into your repo, authenticate with gh inside the sandbox, then run ./ralph.sh --agent copilot. Ralph re-runs Copilot against .agent/tasks.json until the work is done or you hit the iteration cap.

This is the full recipe, from an empty repo to a reviewable diff. If the loop itself is new to you, start with what the Ralph technique is. If you want a wider look at terminal agents before you commit, the field guide is agentic coding CLIs. This post is the canonical Ralph plus Copilot page: everything below is the end-to-end setup.

Why run a Ralph loop with Copilot?

Copilot is the GitHub-native agent. Its CLI runs from the terminal, reads a prompt, edits files, runs shell commands, prints a final message, and exits. That clean exit is the hook a loop needs. Each iteration is a discrete unit of work: spawn the agent, let it do one task, read what it emitted, repeat.

The reason to pick Copilot over another CLI is almost never the model. It is the account. If your team already standardized on GitHub, your identity, your seats, your billing, and your permissions already live there. Copilot authenticates through gh, so the loop rides on the same GitHub login your engineers use every day. There is no separate vendor account to provision, no extra key to rotate, no new invoice to reconcile. For a shop that runs everything through GitHub, that is one less system to babysit.

Ralph supplies the three things a single Copilot CLI call cannot:

A loop, so the agent gets another pass after every commit instead of stopping cold.
Fresh context per iteration, so a long run never rots into a confused, drifting session.
A Docker sandbox boundary, so the agent edits files and runs commands in bypass-permissions mode without that blast radius reaching your real machine.

State lives on disk (the task list, the logs, the git history), not in a chat transcript. That is what lets a stateless Copilot invocation reorient on every pass and still make forward progress across dozens of iterations. The original argument for why a plain Bash loop beats a clever agent runtime is in Geoffrey Huntley’s writeup on Ralph.

Step 1: Install Ralph

Run the installer in your project root. It drops the ralph.sh script and the .agent/ directory into the repo.

npx @pageai/ralph-loop

The installer asks for your dev server URL and port and your default agent, then writes a default implementation-mode setup. Pick copilot when prompted, or set it per run with --agent copilot later. After install, make the script executable if it is not already:

chmod +x ralph.sh

Step 2: Create a PRD and task list

The loop executes a task list. It does not invent one. Before you run anything, turn your requirements into a PRD and a set of task specs with the prd-creator skill.

Open Copilot (or any agent) in plan mode and prompt it with your requirements:

Use the prd-creator skill to help me create a PRD and task list for the below requirements.

An app is already set up with React, Tailwind CSS and TypeScript.

Requirements:
- A SaaS product that helps users manage their finances.
- Track income and expenses, create invoices, generate reports.
- Use shadcn/ui for components and Supabase for the database.
// etc.

The skill writes .agent/prd/PRD.md, a short .agent/prd/SUMMARY.md, and per-task specs under .agent/tasks/, indexed by .agent/tasks.json. Review each task individually before you start. A clear task list with real acceptance criteria is the single biggest factor in whether the loop succeeds. Vague tasks produce vague diffs no matter which agent runs them.

Step 3: Authenticate Copilot through the GitHub CLI

This is the step that sets Copilot apart. The agent runs inside an isolated sandbox, not on your host, so it needs credentials in that environment. Kick off the login action:

./ralph.sh --login --agent copilot

Ralph prints the login command for every supported agent, highlights the Copilot one, and drops you into the sandbox shell. The command it runs to create the box looks like this:

sbx run --name ralph-copilot-<project>-<hash8> copilot .

Inside the sandbox, authenticate with the GitHub CLI. Copilot does not have its own login flow. It leans on gh:

gh auth login

Follow the device-code prompt, pick GitHub.com, and pick HTTPS. Once gh reports you as logged in, Copilot inside that sandbox can act as you. This is not incidental. Ralph’s own auth-failure detection for Copilot watches for the string gh auth login in the agent output, so if the loop starts against an unauthenticated box, it stops and tells you to run exactly that. It never thrashes on a sandbox that can never make progress.

The credential persists in that named sandbox, so later runs attach to the same box already authenticated. That persistence is the whole point of a deterministic sandbox name. Each agent gets its own name, built from the agent slug, the project directory, and an 8-character hash of the absolute path:

ralph-copilot-<project>-<hash8>

Print the exact name for your project without starting a run:

./ralph.sh --print-name --agent copilot

If interactive login through gh ever refuses to stick (Docker Sandboxes persist OAuth tokens on a best-effort basis), there is a token-based fallback. Docker Sandboxes forward environment variables from your shell into the box at create time, not after. So you export the credential in your host shell, delete the stale sandbox, and let Ralph recreate it so the new box picks the value up. Keep the specifics to whatever GitHub token your setup expects and do not paste secrets into the repo. The mechanics of that fallback are the same for every agent; only the credential differs.

If your tasks run a dev server you want to reach from the host, publish the configured port to the Copilot sandbox. The port comes from the dev-server URL you set during install:

./ralph.sh --ports --agent copilot

That expands to an sbx ports call against the Copilot sandbox, for example sbx ports ralph-copilot-<project>-<hash8> --publish 3000:3000. Per-agent names keep state separate: your Copilot sandbox and your Claude sandbox never share credentials or installed tools, so you can run both against the same repo without one clobbering the other.

Step 4: Run the loop with Copilot

With a task list in place and Copilot authenticated, start the loop. The default agent is Claude, so name Copilot explicitly:

# 10 iterations (the default)
./ralph.sh --agent copilot

# 50 iterations for a longer unattended run
./ralph.sh --agent copilot -n 50

# exactly one iteration, good for a smoke test
./ralph.sh --agent copilot --once

The short form -a works too: ./ralph.sh -a copilot -n 5. The --max-iterations 5 long form is equivalent to -n 5. Whatever number you pick is a safety budget, not a target. The loop stops the moment the work is done.

Under the hood, Ralph builds a Copilot CLI command and runs it inside the sandbox. For ./ralph.sh --agent copilot, the expansion is:

sbx run --name ralph-copilot-<project>-<hash8> copilot . -- -p "$PROMPT_CONTENT"

The -p flag hands Copilot the Ralph prompt for this iteration. That prompt is the whole contract: it tells the agent to read the current state from disk, pick one task, do it, prove it works, and commit.

Pass a model and flags after the separator

Everything to the right of Ralph’s own -- separator is forwarded to Copilot. For Copilot specifically, Ralph inserts those extra args right before -p, not after it. So this:

./ralph.sh --agent copilot -- --model <your-model>

expands to:

sbx run --name ralph-copilot-<project>-<hash8> copilot . -- --model <your-model> -p "$PROMPT_CONTENT"

Notice the ordering: --model <your-model> lands before -p "$PROMPT_CONTENT". Do not guess at model identifiers. Pass one your Copilot plan actually supports, and check the Copilot CLI’s own help inside the sandbox if you are unsure which strings it accepts. The rule to remember: everything left of -- configures Ralph (agent, iteration count, login), and everything right of -- configures Copilot.

What happens each iteration

Every pass is mechanical and identical. The agent reorients from disk, does one task, proves it works, and commits.

Find the highest-priority incomplete task in .agent/tasks.json.
Work the steps in .agent/tasks/TASK-{ID}.json.
Run tests, linting, and type checking.
Complete the task, take a screenshot, update the task status, and commit.
Repeat until all tasks pass or the iteration cap is reached.

The key detail is that each iteration spawns a fresh Copilot process with a clean context window. The agent does not carry an hours-long transcript from one task to the next. It reads the current state, does one task, and exits. Continuity is a liability in a long run, not a feature, so the loop deliberately starts cold every time.

flowchart TD
    Start(["./ralph.sh --agent copilot -n 50"]) --> Pick["Pick top task from .agent/tasks.json"]
    Pick --> Spawn["sbx run copilot . -- -p (fresh context)"]
    Spawn --> Work["Copilot reads state, edits files, runs commands"]
    Work --> Verify["Run tests, lint, type check, screenshot"]
    Verify --> Commit["Commit and update task status"]
    Commit --> Check{"Promise tag emitted?"}
    Check -->|"none"| Pick
    Check -->|"COMPLETE"| Done(["exit 0, all tasks done"])
    Check -->|"BLOCKED or DECIDE"| Stop(["exit 2 or 3, wants a human"])

The filesystem and git history are the memory layer. Progress lives in .agent/tasks.json, .agent/logs/LOG.md, the per-task specs, and the git log, not in a chat transcript. The prompt that drives every pass lives in .agent/PROMPT.md, and its default mode is implementation. You can swap it for a refactor, review, or test mode by editing that one file.

One rule keeps the whole thing reliable: one task per invocation. Copilot completes exactly one task, commits, and stops. It never batches several tasks into a single iteration, which is what keeps each commit small and each diff reviewable.

How the loop knows when to stop

A loop that never ends is a money fire, so Ralph stops on an explicit signal rather than a guess. Copilot emits a semantic promise tag in its final message and Ralph reads it:

<promise>COMPLETE</promise> means every task is finished.
<promise>BLOCKED:reason</promise> means the agent needs human help.
<promise>DECIDE:question</promise> means it needs a decision you have to make.

Those map to exit codes, which is what makes the loop scriptable:

./ralph.sh --agent copilot -n 50
echo $?   # 0 COMPLETE, 1 MAX_ITERATIONS, 2 BLOCKED, 3 DECIDE

Exit code 1 is not a failure. It means the loop spent its iteration budget with work still pending, which is exactly what a safety cap is for. Exit codes 2 and 3 mean Copilot wants a human: either a blocker it cannot clear or a decision only you can make. Wiring those into a CI job or a wrapper script lets you fire off an overnight run and get paged only when the agent genuinely needs you.

Steer, debug, and review a Copilot loop

Three things keep a long Copilot run under control.

Steer without stopping

Get inside the sandbox

The sandbox is a normal container you can poke at. List what exists, then open a shell in the Copilot box:

sbx ls
sbx exec -it ralph-copilot-<project>-<hash8> bash

From there you can re-run a failing test by hand, confirm your GitHub session with gh auth status, or read .agent/logs/LOG.md and the per-iteration logs in .agent/history/. When an install fails, the deny-by-default network is usually the cause. Allow the domain it needs:

sbx policy allow network ralph-copilot-<project>-<hash8> registry.npmjs.org

That is a feature, not a bug. The agent installs what the task needs without a path to exfiltrate your source. Reattaching later is safe too: run sbx run ralph-copilot-<project>-<hash8> (no agent slug, no path) to drop back into the same box.

Review the diff in the morning

Because every task is committed separately, the morning review is a git review, not an archaeology dig:

git log --oneline
git diff main...HEAD

Should you use Copilot or another agent?

Ralph is agent agnostic. The supported agents are claude (default), codex, copilot, cursor, gemini, and opencode, and switching is a single flag. The loop machinery is identical across all of them: same task list, same promise tags, same exit codes, same sandbox boundary. The only things that change per agent are the exact CLI invocation and the login flow.

Copilot is the strong pick when your organization already runs on GitHub and you want the agent to inherit that identity instead of standing up a new one. The GitHub-native auth is the differentiator: gh auth login is a command your engineers already know, your GitHub seats already cover the access, and there is no separate account to manage. If you are choosing between backends on the basis of which CLI holds up over a multi-hour run, the head-to-head is in the best agentic CLI for long-running tasks.

Prefer a different backend? The same end-to-end recipe applies. The setup guide for running a Ralph loop with the Cursor CLI covers the Cursor path, and if you want to understand the ralph.sh script itself before you trust it with your repo, read the Ralph loop shell script.

A real Copilot loop, start to finish, is four commands:

# 1. install Ralph and scaffolding
npx @pageai/ralph-loop

# 2. authenticate once (creates the sandbox, you run gh auth login inside it)
./ralph.sh --login --agent copilot

# 3. smoke test a single pass
./ralph.sh --agent copilot --once

# 4. run the loop for real, optionally with a model your plan supports
./ralph.sh --agent copilot -n 50 -- --model <your-model>

Define your tasks in .agent/tasks.json, write a clear .agent/PROMPT.md, sign in with gh, start the loop, and read the commits in the morning.

Frequently asked questions

How do I run a Ralph loop with Copilot?

Install Ralph with npx @pageai/ralph-loop, create a task list, then authenticate with ./ralph.sh --login --agent copilot and run gh auth login inside the sandbox shell. Start the loop with ./ralph.sh --agent copilot. Ralph runs the GitHub Copilot CLI inside a Docker sandbox, starts a fresh context each iteration, and repeats until every task in .agent/tasks.json is done or the iteration cap is reached.

How does Copilot authenticate inside the sandbox?

Through the GitHub CLI. Copilot has no agent-specific login, so you run gh auth login inside the sandbox and Copilot acts as your GitHub identity. Ralph creates the box with ./ralph.sh --login --agent copilot and drops you into a shell to sign in. The credential persists in the named sandbox, so future runs attach to the same authenticated box.

Does ralph.sh support the GitHub Copilot CLI?

Yes. Copilot is one of the supported agents, alongside claude, codex, cursor, gemini, and opencode. Select it with --agent copilot or the short form -a copilot. Ralph builds a Copilot command and runs it inside a deterministic sandbox named ralph-copilot-<project>-<hash8>.

How do I pass a model to Copilot through Ralph?

Put it after the -- separator. Anything to the right of -- is forwarded to Copilot, and for Copilot those args are inserted right before -p. So ./ralph.sh --agent copilot -- --model your-model expands to sbx run ... copilot . -- --model your-model -p with the Ralph prompt. Pass a model your Copilot plan supports rather than guessing at an identifier.

Why choose Copilot over another agent for the loop?

Pick Copilot when your team already standardized on GitHub. Auth rides on the same gh login your engineers use, your GitHub seats cover access, and there is no separate vendor account or key to manage. The loop mechanics are identical across agents, so the choice comes down to which account and CLI fit your setup best.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

How to Run a Ralph Loop With opencode

Sun, 14 Jun 2026 00:00:00 GMT

To run a Ralph loop opencode setup, install Ralph into your project, log in to opencode once inside its sandbox, then run ./ralph.sh --agent opencode. Ralph drives the open-source opencode CLI through its run subcommand, hands it a fresh context window every iteration, and keeps re-running it against your task list until the work is done or you hit the iteration cap.

The reason this pairing is worth its own page: opencode is the open-source, provider-agnostic agent in the lineup, and Ralph is a hackable open Bash script. An open CLI on top of an open loop means you own both ends. You pick the model. You pick the provider. Nothing about the loop is locked to a vendor. This post is the end-to-end recipe, from an empty repo to a reviewable diff.

If the loop itself is new to you, start with what the Ralph technique is. If you want to compare terminal agents before you commit, the field guide is agentic coding CLIs.

Why run opencode in a Ralph loop?

opencode is a terminal-first coding agent with no editor attached. You give it a prompt, it reads files, edits them, runs shell commands, prints a result, and exits. That clean exit is the hook Ralph needs. Each iteration becomes a discrete unit of work: spawn opencode, let it do one task, read what it emitted, then spawn it again.

Two properties make opencode a natural fit for a hackable loop.

It is open source. You can read exactly what the agent does, fork it, and audit its behavior. That matches the spirit of ralph.sh, which is a script you are meant to open and edit, not a black box.
It is provider-agnostic. opencode does not force one model vendor on you. You configure the model and provider opencode supports, and the loop runs identically regardless of which one you chose.

Ralph then supplies the three things a single opencode run cannot give you on its own:

A loop, so the agent gets another pass after every commit instead of stopping.
Fresh context per iteration, so a long run never rots into a confused, drifting session.
A Docker sandbox boundary, so the agent can edit files and run commands in bypass-permissions mode without that blast radius reaching your real machine.

The state lives on disk (the task list, the logs, the git history), not in a chat transcript. That is what lets a stateless opencode invocation reorient on every pass and still make forward progress across dozens of iterations. The Ralph technique itself was popularized by Geoffrey Huntley, and his original writeup on Ralph as a Bash loop is the shortest path to the core idea.

Step 1: Install Ralph

Run the installer in your project root. It drops the ralph.sh script and the .agent/ directory into the repo.

npx @pageai/ralph-loop

The installer asks for your dev server URL and port and your default agent, then writes a default implementation-mode setup. Pick opencode when prompted, or set it per run with --agent opencode later. After install, make the script executable if it is not already:

chmod +x ralph.sh

Step 2: Create a PRD and task list

The loop executes a task list. It does not invent one. Before you run anything, turn your requirements into a PRD and a set of task specs with the prd-creator skill.

Open any agent in plan mode and prompt it with your requirements:

Use the prd-creator skill to help me create a PRD and task list for the below requirements.

An app is already set up with React, Tailwind CSS and TypeScript.

Requirements:
- A SaaS product that helps users manage their finances.
- Track income and expenses, create invoices, generate reports.
- Use shadcn/ui for components and Supabase for the database.
// etc.

Step 3: Log in to opencode inside the sandbox

opencode runs inside an isolated sandbox, not on your host, so it needs credentials in that environment. Authenticate once with the login action:

./ralph.sh --login --agent opencode

Ralph prints the login command for every supported agent, highlights the opencode one, and drops you into the sandbox shell. The command it runs to create the box looks like this:

sbx run --name ralph-opencode-<project>-<hash8> opencode .

Inside the sandbox, authenticate opencode once. Run opencode auth login and follow the prompt to connect your model provider. That is the exact command Ralph points you to if it detects an auth failure at the start of a run, so it never thrashes on a box that can never make progress. The credential persists in that named sandbox, so later runs attach to the same box already logged in.

If your provider prefers a key over an interactive login, Docker Sandboxes forward environment variables at the moment a sandbox is created. Export the provider key opencode expects in your shell, then create the sandbox with ./ralph.sh --login --agent opencode so it picks the value up. Configure the model and provider opencode supports through its own config; Ralph does not hardcode any provider identifiers, which is the whole point of the bring-your-own-provider design.

Each agent gets its own deterministic sandbox name, built from the agent slug, the project directory, and an 8-character hash of the absolute path:

ralph-opencode-<project>-<hash8>

Print the exact name for your project without starting a run:

./ralph.sh --print-name --agent opencode

If your tasks run a dev server you want to reach from the host, publish the configured port to the opencode sandbox. The port comes from the dev-server URL you set during install:

./ralph.sh --ports --agent opencode

That expands to an sbx ports call against the opencode sandbox, for example sbx ports ralph-opencode-<project>-<hash8> --publish 3000:3000. Per-agent names keep state separate: your opencode sandbox and your Claude sandbox never share credentials or installed tools, so you can run both against the same repo without one clobbering the other.

Step 4: Run the loop with opencode

With a task list in place and opencode authenticated, start the loop. The default agent is Claude, so name opencode explicitly:

# 10 iterations (the default)
./ralph.sh --agent opencode

# 50 iterations for a longer unattended run
./ralph.sh --agent opencode -n 50

# exactly one iteration, good for a smoke test
./ralph.sh --agent opencode --once

The short form -a works too: ./ralph.sh -a opencode -n 5. There is also ./ralph.sh --agent opencode --max-iterations 5 if you prefer the long flag. The iteration count is a safety budget, not a target. The loop stops the moment the work is done.

Under the hood, Ralph builds an opencode command and runs it inside the sandbox. This is the detail that sets opencode apart from the other agents: Ralph drives it through the run subcommand, not a -p print flag. For ./ralph.sh --agent opencode, the expansion is:

sbx run --name ralph-opencode-<project>-<hash8> opencode . -- run "$PROMPT_CONTENT"

The run subcommand is opencode’s non-interactive path: it takes a prompt, does the work with full tool access including file writes and shell, and exits. That is exactly what a loop needs, an agent that can do real work without a person approving each step.

Pass a model and flags after the separator

Everything to the right of Ralph’s own -- separator is forwarded straight to opencode, inserted right after run. So this:

./ralph.sh --agent opencode -- <EXTRA>

expands to:

sbx run --name ralph-opencode-<project>-<hash8> opencode . -- run <EXTRA> "$PROMPT_CONTENT"

Use that slot to select the model and provider opencode supports. Because opencode is provider-agnostic, the exact identifiers depend on which provider you configured, so check opencode’s own help for the flags it accepts rather than guessing. The rule to remember: everything left of -- configures Ralph (agent, iteration count, login), and everything right of -- configures opencode.

What happens each iteration

Every pass is mechanical and identical. The agent reorients from disk, does one task, proves it works, and commits.

Find the highest-priority incomplete task in .agent/tasks.json.
Work the steps in .agent/tasks/TASK-{ID}.json.
Run tests, linting, and type checking.
Complete the task, take a screenshot, update the task status, and commit.
Repeat until all tasks pass or the iteration cap is reached.

The key detail is that each iteration spawns a fresh opencode run with a clean context window. The agent does not carry an hours-long transcript from one task to the next. It reads the current state from disk, does one task, and exits. Continuity is a liability here, not a feature: a clean context on every pass is what avoids the context rot that sinks long single-session runs.

flowchart TD
    Start(["./ralph.sh --agent opencode -n 50"]) --> Pick["Pick top task from .agent/tasks.json"]
    Pick --> Spawn["sbx run opencode . -- run (fresh context)"]
    Spawn --> Work["opencode reads state, edits files, runs commands"]
    Work --> Verify["Run tests, lint, type check, screenshot"]
    Verify --> Commit["Commit and update task status"]
    Commit --> Check{"Promise tag emitted?"}
    Check -->|"none"| Pick
    Check -->|"COMPLETE"| Done(["exit 0, all tasks done"])
    Check -->|"BLOCKED or DECIDE"| Stop(["exit 2 or 3, wants a human"])

The filesystem and git history are the memory layer. Progress lives in .agent/tasks.json, .agent/logs/LOG.md, the per-task specs under .agent/tasks/, the per-iteration logs in .agent/history/, and the git log, not in a chat transcript. The prompt that drives every pass lives in .agent/PROMPT.md, alongside .agent/prd/SUMMARY.md, which gives opencode a short project overview on each iteration.

One rule keeps the whole thing reliable: one task per invocation. opencode completes exactly one task, commits, and stops. It never batches several tasks into a single iteration, which is what keeps each commit small and each diff reviewable.

How the loop knows when to stop

A loop that never ends is a money fire, so Ralph stops on an explicit signal rather than a guess. opencode emits a semantic promise tag in its final message and Ralph reads it:

<promise>COMPLETE</promise> means every task is finished.
<promise>BLOCKED:reason</promise> means the agent needs human help.
<promise>DECIDE:question</promise> means it needs a decision you have to make.

Those map to exit codes, which is what makes the loop scriptable:

./ralph.sh --agent opencode -n 50
echo $?   # 0 COMPLETE, 1 MAX_ITERATIONS, 2 BLOCKED, 3 DECIDE

Exit code 1 is not a failure. It means the loop spent its iteration budget with work still pending, which is exactly what a safety cap is for. If opencode is not authenticated when the loop starts, Ralph detects the auth failure, stops, and tells you to run opencode auth login inside the sandbox (via ./ralph.sh --login --agent opencode), so a broken box never burns iterations.

Steer, debug, and review

Three things keep a long opencode run under control.

Steer without stopping

Get inside the sandbox

The sandbox is a normal container you can poke at. List what exists, then open a shell in the opencode box:

sbx ls
sbx exec -it ralph-opencode-<project>-<hash8> bash

From there you can re-run a failing test by hand, confirm auth by running opencode directly, or read .agent/logs/LOG.md and the per-iteration logs in .agent/history/. When an install fails, the deny-by-default network is usually the cause. Allow the domain it needs:

sbx policy allow network ralph-opencode-<project>-<hash8> registry.npmjs.org

That is a feature, not a bug. The agent installs what the task needs without a path to exfiltrate your source. To reattach to a running box later, sbx run ralph-opencode-<project>-<hash8> drops you back in without recreating it.

Review the diff in the morning

Because every task is committed separately, the morning review is a git review, not an archaeology dig:

git log --oneline
git diff main...HEAD

Should you use opencode or another agent?

Ralph is agent agnostic. The supported agents are claude (default), codex, copilot, cursor, gemini, and opencode, and switching is a single flag. opencode earns its place when you want an open-source agent and the freedom to route through whatever model provider you already use. The loop machinery is identical across agents, so the choice comes down to which CLI holds up over a multi-hour run.

The verification stack the loop assumes is the same regardless of agent: Playwright for end-to-end tests, Vitest for unit tests, TypeScript for types, ESLint for linting, and Prettier for formatting. The repo mantra is blunt about it: if you didn’t test it, it doesn’t work. That comparison across CLIs lives in the best agentic CLI for long-running tasks. If you want to strip the loop down to its essentials, read the Ralph loop shell script, and if you would rather drive a proprietary CLI, the companion recipe is running a Ralph loop with the Cursor CLI.

A real opencode loop, start to finish, is four commands:

# 1. install Ralph and scaffolding
npx @pageai/ralph-loop

# 2. authenticate once (creates the sandbox, you log in inside it)
./ralph.sh --login --agent opencode

# 3. smoke test a single pass
./ralph.sh --agent opencode --once

# 4. run the loop for real
./ralph.sh --agent opencode -n 50

Define your tasks in .agent/tasks.json, write a clear .agent/PROMPT.md, configure the model and provider opencode supports, start the loop, and read the commits in the morning.

Frequently asked questions

How do I run a Ralph loop with opencode?

Install Ralph with npx @pageai/ralph-loop, create a task list, log in with ./ralph.sh --login --agent opencode, then run ./ralph.sh --agent opencode. Ralph drives the open-source opencode CLI through its run subcommand inside a Docker sandbox, starts a fresh context each iteration, and repeats until every task in .agent/tasks.json is done or the iteration cap is reached.

Does ralph.sh support opencode?

Yes. opencode is one of the supported agents, alongside claude, codex, copilot, cursor, and gemini. Select it with --agent opencode or the short form -a opencode. Ralph builds an opencode run command and executes it inside a deterministic sandbox named ralph-opencode-<project>-<hash8>.

How does Ralph invoke opencode under the hood?

Ralph uses opencode run rather than a print flag. For ./ralph.sh --agent opencode the expansion is sbx run --name ralph-opencode-<project>-<hash8> opencode . -- run "$PROMPT_CONTENT". Anything you pass after Ralph's own -- separator is inserted right after run, so you can select the model and provider opencode supports.

How do I log in to opencode for the loop?

Run ./ralph.sh --login --agent opencode. It drops you into the sandbox shell where you run opencode auth login and connect your model provider. The credential persists in that named sandbox, so future runs attach to the same box already authenticated. You can also forward a provider key as an environment variable at sandbox creation time.

Can I choose my own model and provider with opencode?

Yes. opencode is provider-agnostic, so you configure the model and provider it supports through its own config or by passing flags after Ralph's -- separator. Ralph does not hardcode any provider identifiers, which keeps the loop portable across whatever backend you already pay for.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

How to Inspect and Debug Inside an AI Agent Sandbox

Wed, 27 May 2026 00:00:00 GMT

When an autonomous agent gets stuck, do not guess from the outside. Open a shell in the running sandbox and look. A Ralph sandbox is a normal container once you are inside it, so you find it with sbx ls, shell in with sbx exec -it <name> bash, and debug the agent the same way you debug any other process. This is the field guide to inspecting and debugging an AI agent sandbox: locating the microVM, getting an interactive shell, reproducing the failure by hand, and reading the network log.

When to get inside the sandbox

A loop driven by Ralph does not fail silently. The agent emits an explicit signal when it cannot proceed: <promise>BLOCKED:reason</promise> when it needs human help (exit code 2) or <promise>DECIDE:question</promise> when it needs a decision (exit code 3). A run that hits the iteration cap exits with 1, and a clean finish exits with 0. The promise text tells you what the agent thinks went wrong. It does not always tell you why.

That gap is what a shell closes. You get inside when a task keeps failing the same way, when an install hangs, when tests pass for you but not for the agent, or when you just want to see the state the agent left behind. Because the agent runs in bypass-permissions mode (see running agents in YOLO mode safely for why that is fine inside a microVM), the inside of the sandbox holds the real evidence: the working tree, the logs, the installed packages, and the exact environment the agent saw.

The sandbox is the same boundary described in the pillar guide, how to run AI coding agents in Docker Sandboxes safely. Debugging it does not weaken that boundary. You are stepping into the contained space on purpose, doing your work, and stepping back out.

Find the sandbox you need to debug

You cannot shell into a sandbox you cannot name. Ralph names every sandbox deterministically, so the name is predictable, but you still want to confirm what is actually running.

List everything with sbx ls

Start with the list:

sbx ls

This prints every sandbox on the machine. The one you want follows the Ralph format:

ralph-<agent>-<current-dir>-<hash8>

A project at /Users/me/Work/My App running Claude shows up as ralph-claude-my-app-a1b2c3d4. If you ran more than one agent against the same project, you will see one sandbox per agent, because the agent slug is part of the name. That is deliberate, so a Claude run and a Codex run never stomp on each other’s state.

Ask Ralph for the exact name

You do not have to read the name off a list. Ralph prints it on the Starting Ralph line at launch, and you can ask for it any time:

./ralph.sh --print-name
./ralph.sh --print-name --agent cursor

The --agent flag targets a specific agent’s sandbox for the same project. Capture the value once and reuse it for every sbx command below, so you are not retyping a hash.

Decode the deterministic name

The name carries information, which helps when you have several sandboxes open. The pieces are documented in the repo’s sandbox naming notes:

<agent> is the agent slug, lowercased: claude, codex, copilot, cursor, gemini, or opencode.
<current-dir> is the basename of the project directory, sanitized to [a-z0-9-].
<hash8> is the first eight hex characters of sha256 of the absolute project path.

The path hash is the part that prevents collisions. Two directories both named app, one at ~/Work/app and one at /tmp/app, get different hashes and therefore different sandboxes. So when sbx ls shows two ralph-claude-app-... entries, the trailing hash is how you tell them apart.

Shell into the sandbox with sbx exec

This is the command you came for. Open an interactive shell:

sbx exec -it ralph-claude-my-app-a1b2c3d4 bash

The -it flags allocate an interactive terminal. Now you are inside the microVM with full control, the same as any container. You can install packages, run the test suite, read files, and poke at the environment the agent ran in.

Navigate to the project path

The project is mounted at the same absolute path it has on your host. If your project lives at /Users/you/Work/my-app on the host, it lives at /Users/you/Work/my-app inside the sandbox too. That is on purpose, so tooling, config files, and lockfiles resolve identically and the agent never trips over a path difference.

So the first move after shelling in is usually:

cd /Users/you/Work/my-app

Now your working directory matches the agent’s. Any relative path the agent used resolves the same way for you.

Run the agent CLI by hand

The most useful trick is driving the agent yourself, interactively, from inside the sandbox. You see exactly what it sees, including the permission mode and the network reality:

sbx exec -it ralph-claude-my-app-a1b2c3d4 bash
cd /Users/you/Work/my-app
claude

Swap claude for codex, copilot, cursor, gemini, or opencode depending on which agent that sandbox was built for. Running the CLI by hand is how you tell apart a prompt problem from an environment problem. If the agent stalls the same way interactively, the issue is the task, the prompt, or the repo state. If it works by hand but fails in the loop, the issue is in how the loop set things up, and you can compare the two.

Reattach a stopped sandbox with sbx run

sbx exec works while the sandbox is running. To reattach the exact sandbox Ralph uses, for a manual login or a longer debugging session, use the attach form of sbx run:

sbx run ralph-claude-my-app-a1b2c3d4

There is one sharp edge here, and it trips people up, so state it plainly. The create form, sbx run --name <name> <agent> ., is create-only. Passing --name for a sandbox that already exists fails with an error that says --name can only be used when creating a new sandbox. So you use the --name create form exactly once, before the sandbox exists, and the bare sbx run <name> attach form every time after.

Ralph handles this branching for you. It probes sbx ls before every iteration and emits the create form when the sandbox is missing and the attach form when it exists. That probe is also why a loop self-heals: if you sbx rm a sandbox mid-run while debugging, the next iteration simply creates it again. Re-running ./ralph.sh, ./ralph.sh --login, or ./ralph.sh --ports is therefore safe at any point.

Debug inside: logs, reproduction, and missing tools

Once you have a shell, the sandbox is just an environment. Three moves cover most debugging sessions.

Read the agent’s own memory layer

Ralph keeps its state on disk, not in chat history, because the filesystem and git history are the memory layer. That means everything the agent knows is sitting in the project, ready to read:

cat .agent/logs/LOG.md
ls .agent/history/
cat .agent/tasks.json
git log --oneline -20

.agent/logs/LOG.md is the running log. .agent/history/ holds per-iteration logs, so you can see what happened on the iteration that broke. .agent/tasks.json is the task lookup table, and the git log shows what the agent actually committed. Reading these in order usually tells you whether the agent thrashed on one task, committed something broken, or stalled waiting on a decision. For the wider picture of making a run auditable from the outside, including live output and screenshots, see observability for autonomous coding agents.

Reproduce the failing command

The fastest way to understand a failure is to run the thing that failed. Inside the sandbox, at the project path, run the verification stack the loop assumes:

npm test
npx tsc --noEmit
npx eslint .
npx playwright test

If the agent reported a failing test, run that test directly and read the full output without the loop’s framing. The repo mantra is “if you didn’t test it, it doesn’t work,” and the same applies to your debugging: reproduce the exact failure before you theorize about it. Because you are inside the same microVM the agent used, a failure you reproduce here is the real failure, not a near miss caused by a different machine.

Install missing tooling

Sometimes the agent is blocked because a binary it needs is not installed. You have full root-style control inside the sandbox, so install it and confirm the theory:

apt-get update && apt-get install -y <package>

If an install itself fails, that is almost never a package manager bug. It is the network gate, which is the next section.

Debug the network with sbx policy log

Docker Sandboxes are deny-by-default on outbound HTTP and HTTPS. So the single most common “the agent is stuck” cause is a blocked connection: npm install fails, an API call is refused, or a package download hangs. The gate is doing its job, but you need to see what it blocked.

Read the connection history:

sbx policy log

This shows which outbound connections the sandbox attempted and which the policy allowed or denied. List the active rules to see what is currently permitted:

sbx policy ls

When the log shows a denied host the task legitimately needs, allow that specific domain rather than opening everything:

sbx policy allow network ralph-claude-my-app-a1b2c3d4 registry.npmjs.org

Allow several at once with a comma-separated list, which is the usual case when an install is blocked:

sbx policy allow network ralph-claude-my-app-a1b2c3d4 "*.npmjs.org,*.pypi.org,files.pythonhosted.org,github.com"

Changes take effect immediately and persist across sandbox restarts. Resist the urge to debug with the full-open "**" rule and leave it there, because that throws away half the boundary. The disciplined way to build an allowlist that lets installs through while keeping exfiltration out is covered in network policies for AI agent sandboxes. The primary reference for the policy engine is the Docker Sandboxes documentation.

A map of debug entry points

There are only a handful of ways into and out of a sandbox, and they compose cleanly. This is the whole surface you work with.

flowchart LR
  Host["Your machine (host)"]
  subgraph Entry["Debug entry points"]
    List["sbx ls: find the name"]
    Shell["sbx exec -it name bash: interactive shell"]
    Attach["sbx run name: reattach the loop sandbox"]
    NetLog["sbx policy log: connection history"]
    Stop["sbx stop name: end the session"]
  end
  subgraph Sandbox["Sandbox: ralph-claude-my-app-a1b2c3d4"]
    Proj["Project at the same path as the host"]
    Logs[".agent/logs, .agent/history, git log"]
    CLI["Agent CLI you can run by hand"]
    Net["Network gate: deny-by-default"]
  end
  Host --> List
  Host --> Shell
  Host --> Attach
  Host --> NetLog
  Host --> Stop
  Shell --> Proj
  Shell --> Logs
  Shell --> CLI
  Attach --> CLI
  NetLog --> Net

sbx ls gives you the name. sbx exec and sbx run put you inside. sbx policy log explains network failures from the outside. sbx stop ends the session. You rarely need anything else.

Clean up with sbx stop

When you finish a manual debugging session, stop the sandbox you were poking at:

sbx stop ralph-claude-my-app-a1b2c3d4

Stopping targets only that one name. Sandboxes you started for other agents in the same project are left alone. Ralph runs this same command for you through its exit trap when a loop ends, by normal exit, by a double Ctrl+C, or by any path that fires the trap, and the cleanup is guarded so it runs at most once.

Stopping is not deleting. A stopped sandbox can be reattached later with sbx run <name>, which is handy when you want to come back to the same state. When you are truly done and want the microVM gone, remove it explicitly:

sbx rm ralph-claude-my-app-a1b2c3d4

If sbx is not installed at all, Ralph fails fast before any of this with a clear pointer to the Docker Sandboxes getting-started guide rather than a confusing downstream error.

A debugging session, end to end

Putting the moves in order, here is what a real session looks like when a loop reports BLOCKED.

First, get the name and confirm the sandbox is there:

./ralph.sh --print-name
sbx ls

Shell in and go to the project path:

sbx exec -it ralph-claude-my-app-a1b2c3d4 bash
cd /Users/you/Work/my-app

Read what the agent recorded, then reproduce the failure it hit:

cat .agent/logs/LOG.md
git log --oneline -10
npm test

If the failure is a blocked install, check the network log from your host in another terminal, allow the domain, and retry the install inside the sandbox:

sbx policy log
sbx policy allow network ralph-claude-my-app-a1b2c3d4 registry.npmjs.org

If the failure is a task or prompt problem, run the agent CLI by hand and watch it work the task interactively. When you understand the cause, exit the shell, fix the task spec or the prompt on the host, and let the loop pick up where it left off. Ralph re-probes the sandbox on the next iteration, so your fix runs in the same contained environment.

This is the Ralph technique applied to its own failures. The loop, in the tradition of Geoffrey Huntley’s original Ralph writeup, keeps its state on disk so you can always step in, read the evidence, reproduce the problem, and step back out. The sandbox is contained, so debugging it costs you nothing on the host. The worst case stays cheap, and the agent gets back to work.

Frequently asked questions

How do I open a shell inside a running AI agent sandbox?

Find the sandbox name with sbx ls or with ./ralph.sh --print-name, then run sbx exec with the interactive flags and bash, for example sbx exec -it ralph-claude-my-app-a1b2c3d4 bash. You now have full control inside the microVM, so you can navigate to the project path, run tests, install packages, and inspect files like any container.

What is the difference between sbx exec and sbx run for debugging?

Use sbx exec with -it and bash to open an interactive shell in a sandbox that is already running. Use sbx run with the name to reattach the sandbox Ralph uses for a manual login or a longer session. The create form sbx run --name name agent dot is create-only and only works the first time, before the sandbox exists.

Why does an install or API call fail inside the sandbox?

Docker Sandboxes block outbound network by default. Run sbx policy log to see which connections were denied, then allow the specific domain with sbx policy allow network using the sandbox name. Allow only the hosts the task needs, such as registry.npmjs.org or the comma-separated npm, PyPI, and GitHub domains, rather than opening all traffic.

Where does the agent store the logs I should read when it gets stuck?

Ralph keeps its state on disk inside the project, not in chat history. Read .agent/logs/LOG.md for the running log, list .agent/history for per-iteration logs, check .agent/tasks.json for the task table, and run git log to see what was committed. Together these usually show whether the agent thrashed on a task or stalled waiting on a decision.

How do I clean up a sandbox after debugging?

Run sbx stop with the sandbox name to stop only that sandbox; sandboxes for other agents are untouched. Stopping is not deleting, so you can reattach later with sbx run and the name. When you want the microVM gone for good, remove it with sbx rm. Ralph also stops its own sandbox automatically through its exit trap when a loop ends.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

Network Policies for AI Agent Sandboxes

Thu, 21 May 2026 00:00:00 GMT

An agent needs some network and not all of it. A Docker Sandbox blocks outbound HTTP and HTTPS by default, so the agent starts with zero reach and you grant exactly the domains a task needs with sbx policy allow network. That is the whole ai agent sandbox network policy model: deny everything, then allowlist the package registries, code hosts, and APIs the work requires, and nothing else. This guide shows the commands, the matching rules, and a practical allowlist you can paste for a normal project. It is the network half of the Docker Sandboxes pillar guide.

Why a sandbox blocks the network by default

Filesystem isolation is only half of a sandbox boundary. The other half is the network. An agent with unrestricted outbound access can fetch arbitrary code, run a curl | bash it found in a README, and in the worst case send your source or secrets to a host you never approved. That last risk is the one that should keep you honest. The agent does not need to be malicious. It is a probabilistic system running shell commands, and a shell command that uploads a file looks exactly like a shell command that downloads one.

So Docker Sandboxes ship with a deny-by-default network posture. All outbound HTTP and HTTPS to domains not on the allowlist is blocked, and all non-HTTP protocols (raw TCP, UDP including DNS, and ICMP) are blocked at the network layer, as documented in the default security posture reference. Traffic to private IP ranges, loopback, and link-local addresses is blocked too, so the agent cannot reach back into your LAN or a cloud metadata endpoint.

The practical symptom is that npm install fails, a pip install hangs, or an API call is refused inside the sandbox. That is not a bug. That is the gate doing its job. You fix it by allowlisting the specific domains the task needs, not by opening everything. The point of the sandbox was to make the agent fearless inside a contained blast radius, and a wide-open network puts a hole in the wall you built.

Docker offers three starting policies, described in the policies documentation:

Open: all outbound traffic allowed, equivalent to a global allow-all rule. No restrictions.
Balanced: default deny with a baseline allowlist covering common AI provider APIs, package managers, code hosts, container registries, and cloud services. You extend it with sbx policy allow.
Locked Down: everything blocked, including model provider APIs like api.anthropic.com. You allow each host explicitly.

Most Ralph users sit on Balanced or stricter. If you chose Balanced, package installs from the big registries often work out of the box and you only add what is missing. If you chose Locked Down, you allow even the model API the agent talks to. Check which one you are on before debugging a blocked request.

How a request flows through the network gate

Every outbound connection the agent makes hits the policy gate before it leaves the sandbox. The gate compares the destination against your allow and deny rules, and if nothing matches, the default policy decides. On a deny-by-default install, nothing matching means blocked.

flowchart TD
  Agent["Agent in YOLO mode"] -->|"outbound request to a host"| Gate{"Network policy gate"}
  Gate -->|"matches a deny rule"| Block["Blocked: connection refused"]
  Gate -->|"matches an allow rule"| Pass["Allowed: leaves the sandbox"]
  Gate -->|"matches nothing (deny-by-default)"| Block
  Pass --> Net["Internet: only allowlisted hosts"]
  Block --> Log["Recorded in sbx policy log"]

The diagram is the mental model. The agent never talks to the internet directly. It talks to a gate, and the gate enforces a list you control from the host. You set that list once for a project and stop thinking about individual requests.

How to allow a domain with sbx policy

Grant access with sbx policy. Changes take effect immediately and persist across sandbox restarts. You target a single sandbox by passing its name, or every sandbox on the machine with the global flag -g. Get the name from sbx ls or from Ralph directly:

./ralph.sh --print-name
./ralph.sh --print-name --agent codex

Ralph builds a deterministic sandbox name in the form ralph-<agent>-<current-dir>-<hash8>, so a project at /Users/me/Work/my-app running Claude becomes ralph-claude-my-app-a1b2c3d4. Use that string wherever a command below shows a name.

Allow one domain for one sandbox

The base command takes a sandbox name and a domain:

sbx policy allow network ralph-claude-my-app-a1b2c3d4 api.example.com

That sandbox can now reach api.example.com. Nothing else changed, and no other sandbox was affected.

Allow several domains at once

Pass a comma-separated list instead of a single host. This is the common case when a package install is blocked and you want to fix it in one command:

sbx policy allow network ralph-claude-my-app-a1b2c3d4 "*.npmjs.org,*.pypi.org,files.pythonhosted.org,github.com"

Quote the list so your shell does not try to glob the asterisks. Each entry is matched independently against outbound requests.

Apply a rule to every sandbox with -g

When a domain is something every project on your machine needs (a model provider API, your internal package mirror), set it globally:

sbx policy allow network -g "api.anthropic.com,*.npmjs.org,*.pypi.org"

Global rules are convenient and also a bigger commitment, because they widen the network for sandboxes you have not thought about yet. Prefer per-sandbox rules for anything task-specific and reserve -g for genuinely universal hosts.

The allow-all escape hatch

You can open a single sandbox completely with the double-asterisk wildcard, which opts it out of network filtering:

sbx policy allow network ralph-claude-my-app-a1b2c3d4 "**"

Use "**" sparingly and on purpose. It is the right tool when you genuinely cannot enumerate the domains a task needs and you accept the tradeoff for that one sandbox. It is the wrong default, because it throws away the network half of the boundary you set up the sandbox to get. If you find yourself reaching for "**" on every run, that is a signal to capture the real allowlist instead, which the practical section below walks through.

Inspect, log, and revoke

You do not have to guess what the gate is doing. List the active rules:

sbx policy ls

Watch what the agent actually tried to reach, which is the fastest way to turn a blocked install into a precise allow rule:

sbx policy log

And remove access with the mirror of allow. A deny rule blocks a host even inside a broader allow:

sbx policy deny network ralph-claude-my-app-a1b2c3d4 ads.example.com
sbx policy deny network -g telemetry.example.com

The workflow that scales is: run the task, read sbx policy log for the refused hosts, add a tight allow rule for the ones the task legitimately needs, and re-run. After two iterations you usually have the exact allowlist a project needs, and you never touched "**".

How domain matching works

The matching rules are simple once you have seen them, and getting them wrong is the usual reason an allow rule appears to do nothing. The policies reference is the source of truth, and here is the working summary.

Exact domains versus wildcard subdomains

A bare domain matches only itself:

example.com matches example.com on any port. It does NOT match api.example.com.
*.example.com matches subdomains like api.example.com and cdn.example.com. It does NOT match the bare example.com.

To cover both the root and its subdomains, list both patterns:

sbx policy allow network ralph-claude-my-app-a1b2c3d4 "example.com,*.example.com"

This trips people up constantly. A registry that serves its index from the apex domain and its tarballs from a CDN subdomain needs both entries, or installs stall halfway through.

Ports

Append a port to scope a rule to one port:

example.com:443 matches requests to example.com on port 443, the default HTTPS port.
*.example.com:443 matches any subdomain on port 443.
example.com with no port matches any port.

Non-HTTP TCP traffic such as SSH is blocked by default and can be allowed by adding a rule for the destination IP address and port, for example sbx policy allow network -g "10.1.2.3:22". UDP and ICMP are blocked at the network layer and cannot be unblocked with a policy rule, so do not expect to ping out or run a custom UDP protocol from inside the sandbox.

Most specific wins, and deny beats allow

When several patterns could match one request, the most specific pattern decides. The order runs from an exact hostname with a port, to an exact hostname on any port, to wildcard patterns (longest match first), to catch-all wildcards, and finally the default policy. That specificity is what lets you block a broad pattern while allowing a narrow exception. You can deny example.com and *.example.com, then allow api.example.com:443, and only that one host and port gets through.

For the case people ask about most: when an allow rule and a deny rule both match a request at the same specificity, the deny rule wins. Deny is the safer default to lose to, and it means you can layer a tight deny over a broad allow without worrying that the allow quietly re-opens the host.

Why this matters: installs versus exfiltration

The reason to bother with any of this is that the two things you want from the network point in opposite directions.

You want package installs to work. An autonomous agent that cannot run npm install, pip install, or cargo fetch is an agent that stalls on its first dependency and burns iterations doing nothing useful. Installs need the registries, the CDNs that serve the actual artifacts, and usually a code host for git dependencies.

You do not want exfiltration to work. The same outbound channel that pulls a tarball in can push a file out. An agent that has read your project (the whole point of the shared workspace) and unrestricted network can, in principle, POST your source or a leaked credential to any host. You are not assuming the model is hostile. You are removing the capability so a confused or prompt-injected agent cannot do the damage even by accident.

A tight allowlist resolves the tension. Installs flow to the registries and code hosts you named, and there is no open path to an arbitrary collection endpoint. The narrower the list, the smaller the surface. This is the same argument the pillar makes for the filesystem, applied to the wire: enforce the boundary from the outside, and keep the grant minimal. For the broader case on why every autonomous run belongs behind a boundary you control rather than a permission prompt the agent can blow past, the Docker Sandboxes pillar is the place to start.

A practical allowlist for a typical project

Here is a concrete starting point for a JavaScript or Python project that pulls dependencies and clones a few git repos. Get the sandbox name, then grant the registries and code host in one command.

For an npm-based project:

./ralph.sh --print-name
sbx policy allow network ralph-claude-my-app-a1b2c3d4 "registry.npmjs.org,*.npmjs.org,github.com,*.githubusercontent.com,codeload.github.com"

For a Python project add the PyPI hosts:

sbx policy allow network ralph-claude-my-app-a1b2c3d4 "pypi.org,*.pypi.org,files.pythonhosted.org"

A few notes on why those specific entries:

registry.npmjs.org is the index, and *.npmjs.org covers the related hosts npm reaches during an install. Listing both the apex and the wildcard avoids the half-finished install problem.
github.com handles git operations, codeload.github.com serves tarball downloads for git dependencies, and *.githubusercontent.com serves raw files and release assets. Git installs that work for the clone but fail on the download usually need codeload.github.com.
pypi.org is the index and files.pythonhosted.org is where the wheels and source distributions actually live, so PyPI needs both.

If your agent talks to a model API from inside the sandbox (you are on Locked Down, or you run the CLI by hand in there), allow that host too, for example api.anthropic.com for Claude. On a Balanced policy these are often already covered by the baseline allowlist, so check sbx policy ls before adding duplicates.

Then run the loop and walk away. The agent works in bypass-permissions mode, but the network gate is one of the walls that makes that safe:

./ralph.sh -n 50

When the loop finishes, Ralph stops the sandbox through its exit trap. Your allowlist persists with the sandbox, so the next run starts from the same known-good network posture instead of a blank deny.

Where network policy fits the rest of the boundary

A network policy is one wall, not the whole house. The sandbox also keeps the agent out of your home directory and off your host Docker daemon, which is the filesystem side of the same idea. If you are weighing a Docker Sandbox against a container you wire up yourself, the network gate is a good example of the difference, and Docker Sandboxes versus plain containers for AI agents covers where a hand-rolled setup tends to leak.

When a request is blocked and you are not sure why, get inside and look. The sandbox is a normal container from the inside, so you can reproduce the failing request, read DNS, and watch sbx policy log from the host at the same time. The full routine for that lives in how to inspect and debug inside an AI agent sandbox.

Finally, the network you allow depends on which agent CLI you run and what it phones home to. Each tool reaches a slightly different set of hosts for auth, models, and telemetry, so the allowlist for a Codex run is not identical to a Gemini run. The agentic coding CLIs guide is the cross-hub companion for picking a CLI and knowing what it expects from the wire. Ralph itself is a hackable Bash loop in the tradition of Geoffrey Huntley’s original Ralph technique, so if a policy rule needs to live somewhere repeatable, it is plain shell you can script next to the loop.

Set the allowlist once, keep it minimal, and let the agent run. Installs go through, exfiltration does not, and the gate is something you can read in one sbx policy ls.

Frequently asked questions

What is the default network policy for a Docker Sandbox?

Deny-by-default for outbound HTTP and HTTPS. Any domain not on the allowlist is blocked, and non-HTTP protocols like raw TCP, UDP, DNS, and ICMP are blocked at the network layer. Docker also offers an Open policy that allows everything and a Locked Down policy that blocks even model provider APIs, so check which one your install uses before debugging a refused request.

How do I allow a domain for an AI agent sandbox?

Use sbx policy allow network with the sandbox name and the domain, for example sbx policy allow network ralph-claude-my-app-a1b2c3d4 api.example.com. Pass a comma-separated list to allow several at once, add the -g flag to apply the rule to every sandbox on the machine, and quote any pattern that contains an asterisk so your shell does not expand it.

Why does my allow rule for example.com not match api.example.com?

Because a bare domain matches only the exact host. example.com does not match its subdomains, and the wildcard form star-dot-example.com does not match the bare root domain. To cover both the apex and its subdomains, allow both patterns in one rule, such as example.com and star-dot-example.com.

What happens when an allow rule and a deny rule both match a request?

The most specific matching pattern wins overall, running from an exact hostname with a port, to an exact hostname on any port, to wildcards, to catch-all rules, and finally the default policy. When an allow and a deny match at the same specificity, the deny rule wins, so you can layer a narrow deny over a broad allow safely.

How do I see which hosts the agent tried to reach?

Run sbx policy ls to list the active allow and deny rules, and sbx policy log to see the connection history including blocked attempts. Reading the log is the fastest way to turn a failed install into a precise allow rule, because it tells you exactly which hosts were refused so you can add only those.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

Running Agents in YOLO Mode (--dangerously-skip-permissions) Safely

Fri, 15 May 2026 00:00:00 GMT

Yes, you can run an agent with --dangerously-skip-permissions safely, but only when the agent is locked inside a sandbox. The exact same flag is reckless on your laptop and a non-event inside a Docker Sandbox microVM. The flag never changes. What changes is what the agent can reach when it stops asking permission. This post explains what YOLO mode does, why you want it for unattended loops, and the one rule that makes dangerously skip permissions safely an honest phrase instead of a contradiction.

What “YOLO mode” actually means

YOLO mode is any configuration where the agent stops asking you to approve commands and just executes them. No “can I run this?” prompt, no confirmation step, no human in the loop on each shell call. The agent reads a task, decides what to do, and does it.

That is the entire appeal and the entire risk in one sentence. The appeal is speed and autonomy. The risk is that you have removed the only gate between a probabilistic model and a real shell.

Claude Code: —dangerously-skip-permissions

In Claude Code the flag is --dangerously-skip-permissions. There is an equivalent longer form, --permission-mode bypassPermissions, documented in the Claude Code docs. Both do the same thing: the agent skips the per-action approval prompt for the rest of the session.

claude --dangerously-skip-permissions
claude --permission-mode bypassPermissions

The name is refreshingly honest. The word “dangerously” is in the flag because Anthropic wants you to feel a little sick typing it on a machine that has your credentials on it. That instinct is correct. The fix is not to avoid the flag. The fix is to change where you run it.

The same idea in other agents

Every serious agent CLI has its own version of this switch, because every long autonomous run needs it. The Codex CLI has a full-auto mode. Gemini, Cursor, Copilot, and opencode each expose an auto-accept or yolo style setting that turns off interactive approvals. The spelling differs per tool, and you do not have to memorize each one, because Ralph Loop launches each supported agent in bypass-permissions mode for you. Pass any extra agent-specific flags after a -- separator:

./ralph.sh --agent codex -- --model gpt-5.5
./ralph.sh -a gemini -- --model pro

Supported agents are claude (the default), codex, copilot, cursor, gemini, and opencode. The common thread across all of them is the same trade. You give up the approval prompt to get an agent that can work without you.

Why you want YOLO mode for unattended loops

Here is the case for turning the prompts off, because it is easy to read “dangerous” and conclude you should always approve commands by hand. You should not, and the reason is structural.

An autonomous loop runs the agent many times. A single iteration of a Ralph loop does real work: it finds the highest-priority incomplete task in .agent/tasks.json, works the steps in the task spec, runs tests, linting, and type checks, commits, and repeats. Across ./ralph.sh -n 50 that is fifty iterations, each one issuing dozens of shell commands. If every command needs your approval, the loop is not autonomous. It is a very slow pair-programming session where you are the bottleneck and you are asleep.

The whole point of running an agent overnight is that you are not there. A permission prompt at 3am is a permission prompt that blocks forever. The agent stalls on the first npm install waiting for a yes that never comes, and you wake up to a loop that did nothing for eight hours.

So unattended runs and per-command approval are mutually exclusive. You either babysit, or you go YOLO. For a long loop, babysitting defeats the purpose, which means YOLO mode is not an edge case. It is the normal operating mode for any agent meant to run while you are away. If you want the deeper version of this argument applied to a single CLI, the run Claude Code in a loop guide walks through the same trade for autonomous Claude Code runs.

The one rule: only go YOLO when the blast radius is contained

Now the rule that makes all of this safe. Run YOLO mode only when the blast radius is contained. The blast radius is everything the agent can touch when it stops asking. Your job is to make that set small, disposable, and external to anything you care about.

A permission prompt is not a security boundary. When the agent asks “can I run this command?” and you click yes, you are the boundary, and you are slow, distracted, and often not awake. When you tell the agent to stop asking, you have not made the agent safe. You have removed the only thing standing between the model and your filesystem. The real fix is to put a wall around the agent that the agent cannot reach through.

On your host, that wall does not exist. An agent running with your user account can read your SSH keys, your ~/.aws/credentials, your browser session cookies, and every other git repository you have checked out. It can push to remotes, delete files, and run a curl | bash it found in a README. None of that requires malice. It is a probabilistic system executing shell commands, and shell commands do not have an undo. For the longer version of why every autonomous run belongs behind a wall, read why you should sandbox every autonomous coding agent.

Inside a Docker Sandbox, the wall is real. A Docker Sandbox is not a plain docker run. It is a lightweight microVM with its own guest kernel, documented in the Docker Sandboxes docs. The agent sees your project directory and a network gate. It does not see the rest of your machine. Run --dangerously-skip-permissions in there and “anything the agent can do” now means “anything it can do inside a microVM that only contains one project directory and a locked-down network.” The dangerous flag becomes a non-event, because the danger had a target on the host and the sandbox removed the target.

This is the inversion worth internalizing. You are not making the agent trustworthy. You are making trust unnecessary by shrinking the blast radius to something you can reset with git or throw away entirely.

flowchart TB
  subgraph Laptop["YOLO on your laptop (host)"]
    HAgent["Agent: --dangerously-skip-permissions"]
    HAgent --> Keys["SSH keys, cloud creds, cookies"]
    HAgent --> Repos["Every other git repo"]
    HAgent --> Net1["Open network: fetch any URL"]
  end
  subgraph Box["YOLO inside a Docker Sandbox"]
    SAgent["Agent: --dangerously-skip-permissions"]
    SAgent --> Proj["Shared project directory only"]
    SAgent --> Gate["Network gate: deny-by-default"]
    SAgent -. "no path to" .-> HostHome["Host home directory"]
  end

Same flag in both boxes. The only difference is the box. On the left, “skip permissions” means skip the last protection your machine had. On the right, it means move fast inside a container that contains nothing precious.

How Ralph runs YOLO mode inside a named sandbox

You can wire this up by hand: create a microVM, launch the agent with the bypass flag, and tear it down when you are done. The point of Ralph is that you do not have to. It computes the sandbox name, checks that the sbx CLI exists, decides whether to create or attach, launches the agent in bypass-permissions mode, and stops the sandbox on exit. Ralph is a hackable Bash loop in the tradition of Geoffrey Huntley’s original Ralph technique, and the YOLO plumbing is part of what it automates.

Answering “Yes” to bypass permissions inside the sandbox

The first time you launch an agent in bypass mode, the CLI shows a one-time warning that asks you to confirm you really want to skip permission prompts. With Ralph, you hit that confirmation inside the sandbox, not on your host, which is exactly where you want to be saying yes. Authenticate and accept the bypass warning in one step with the login action:

./ralph.sh --login
./ralph.sh --login --agent codex

This opens the selected agent inside its correctly named sandbox. You answer the bypass-permissions prompt once, in the microVM, and from then on the agent runs without prompts inside that contained environment. Saying yes to “skip permissions” feels very different when the worst case is a disposable container instead of your home directory.

The deterministic sandbox name is the boundary

Ralph names every sandbox deterministically so the same project and agent pair always reuses the same microVM. The format is:

ralph-<agent>-<current-dir>-<hash8>

The <agent> slug is the lowercased agent name, <current-dir> is the sanitized basename of your project directory, and <hash8> is the first 8 hex characters of a sha256 of the absolute project path. A project at /Users/me/Work/My App running Claude becomes ralph-claude-my-app-a1b2c3d4. The path hash keeps two same-named directories on different paths from colliding, and the agent slug in the name means switching --agent gives you a separate sandbox rather than a surprising state swap.

You never have to memorize it. Ralph prints the name on its startup line, and you can ask for it directly:

./ralph.sh --print-name
./ralph.sh --print-name --agent cursor

That name is the handle for everything else: the sandbox you shell into, the sandbox you allowlist a domain for, and the sandbox Ralph stops on exit.

Create versus attach, every iteration

Each iteration of the loop probes whether the deterministic sandbox already exists. Iteration one usually creates it. Iteration two and onward attach to it. If you manually sbx rm the sandbox mid-run, the next probe simply creates it again. That re-probe is what makes a long YOLO run resilient to you poking at the sandbox by hand.

flowchart TD
  Start["./ralph.sh -n 50"] --> Name["Compute name: ralph-agent-dir-hash8"]
  Name --> CheckSbx{"sbx installed?"}
  CheckSbx -->|"no"| Fail["Exit with docs link"]
  CheckSbx -->|"yes"| Iter["Start iteration"]
  Iter --> Probe{"sandbox exists?"}
  Probe -->|"no"| Create["sbx run --name ... agent ."]
  Probe -->|"yes"| Attach["sbx run name"]
  Create --> Work["Agent works one task in YOLO mode"]
  Attach --> Work
  Work --> Signal{"completion signal?"}
  Signal -->|"COMPLETE"| Done["Exit 0, then sbx stop"]
  Signal -->|"keep going"| Iter

The loop stops on an explicit signal, not a vibe. The agent emits a promise tag: <promise>COMPLETE</promise> when all tasks are done, <promise>BLOCKED:reason</promise> when it needs human help, or <promise>DECIDE:question</promise> when it needs a decision. Those map to exit codes 0, 2, and 3, with 1 reserved for hitting the iteration cap. When the loop ends, Ralph stops the sandbox through its exit trap and hands you back a contained microVM you can inspect or discard.

A safe YOLO run, end to end

Putting the pieces in order, here is what a clean bypass-permissions run looks like. None of these steps put the agent’s hands on your host.

First, install Ralph in your project:

npx @pageai/ralph-loop

Next, authenticate the agent inside its sandbox and accept the bypass-permissions warning once, in the microVM:

./ralph.sh --login

If the task needs network access for installs, allowlist only the domains it needs instead of opening everything. Get the name, then add a rule:

./ralph.sh --print-name
sbx policy allow network ralph-claude-my-app-a1b2c3d4 "*.npmjs.org,github.com"

The network gate matters as much as the filesystem boundary when the agent runs unattended in YOLO mode. A tight allowlist lets installs through and keeps exfiltration out. The full treatment of building that allowlist lives in network policies for AI agent sandboxes.

Then run the loop and walk away. The agent runs with permissions bypassed, but the sandbox is the boundary, so fast and contained are the same thing:

./ralph.sh -n 50

If something looks off mid-run, shell in and look. The sandbox is a normal container from the inside:

sbx exec -it ralph-claude-my-app-a1b2c3d4 bash

When the loop finishes, Ralph stops the sandbox for you. The agent skipped every prompt and ran at full speed, and your host never had its hands on it. This is the default posture Ralph ships, and the broader setup is covered in the pillar guide on running AI coding agents in Docker Sandboxes safely.

Where YOLO mode still bites

A sandbox is a strong boundary and not a magic one. Two limits are worth naming so you do not over-trust the setup.

First, the project directory is shared, which is the entire point, so the agent can absolutely wreck your working tree. The protection there is git, not the sandbox. Commit often, work on a branch, and treat the sandbox as protection for everything outside the project rather than a substitute for version control inside it. A YOLO agent that thrashes on a bad task can still produce a messy diff. The fix is the same as for any agent: clean tasks, frequent commits, and a verification gate of tests, type checks, and linting on every iteration.

Second, whatever you allowlist on the network is genuinely reachable. If you grant a domain that can receive uploads, an agent in YOLO mode could in principle send data there. A "**" allow-all rule throws the whole network surface wide open and undoes half the reason you built the sandbox. Treat network grants like firewall rules: minimal, specific, and reviewed.

Inside those limits, the model is simple and it holds. Skip permissions only when the blast radius is a disposable microVM, enforce the boundary from the outside, and let the agent be fearless where fearless is cheap.

Frequently asked questions

Is it safe to run an agent with --dangerously-skip-permissions?

It is unsafe on your host and safe inside a Docker Sandbox. On the host the flag gives the agent full shell access with no confirmation, so a single bad command can touch your SSH keys, credentials, or other repositories. Inside a microVM sandbox the same flag only grants access to the shared project directory and an allowlisted network, so the worst case is something you can reset with git or throw away.

What is YOLO mode for an AI coding agent?

YOLO mode is any configuration where the agent stops asking you to approve each command and just executes. In Claude Code it is the flag --dangerously-skip-permissions, also written as --permission-mode bypassPermissions. Other agents have their own full-auto or auto-accept setting that does the same thing.

Why do unattended agent loops need bypass-permissions mode?

A long loop issues many shell commands per iteration. If every command needs your approval, the loop blocks the moment you step away and does nothing until you return. Bypass-permissions mode is what lets an agent run overnight without a human approving each action.

Does Ralph Loop run agents in YOLO mode by default?

Yes. Ralph launches each supported agent in bypass-permissions mode because the Docker Sandbox is the boundary. You accept the one-time bypass warning inside the sandbox during ./ralph.sh --login, and every iteration after that runs without prompts inside the contained microVM.

Can a sandboxed YOLO agent still cause damage?

It can damage the shared project directory, since that directory is shared on purpose, so commit often and work on a branch. It can also reach any network domain you allowlist, so keep the allowlist minimal and avoid the allow-all double-star rule. It cannot reach the rest of your host, which is the boundary the sandbox enforces.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

Spec-Driven Development vs Vibe Coding: When Each One Wins

Sun, 10 May 2026 00:00:00 GMT

Vibe coding wins when the code is disposable. Spec-driven development wins when the code has to survive: production systems, code other people maintain, and anything an autonomous agent builds while you are asleep. The split is not about taste. It is about whether the work has verifiable acceptance criteria or just a feeling that the output looks right.

This post defines both honestly, including where vibe coding is genuinely the correct choice. Then it covers why an autonomous loop has no choice but to go spec-driven, what vibe coding actually costs once it scales past one person and one afternoon, and how to pick per task instead of picking a religion. It ends with how Ralph leans spec-driven through a PRD and a task list, without forcing you to spec a five line script.

What vibe coding actually is

Vibe coding is writing code by feel. You describe what you want in loose terms, you read the output, you eyeball whether it looks correct, and you keep nudging until it runs. The acceptance test is your gut. The spec lives in your head and changes as you go.

For an AI workflow, vibe coding means prompting an agent with intent and judging the result by reading it. “Add a settings page.” “Make this faster.” “Fix the layout on mobile.” You accept the diff because it looks plausible and the page renders, not because a test confirmed a specific condition.

This is not an insult. Vibe coding is the fastest way to explore an idea you do not fully understand yet. When the goal is to learn the shape of a problem, writing a spec first is premature: you do not know enough to write a good one. You vibe a spike, see what the problem actually wants, then throw the spike away.

Where vibe coding is genuinely fine:

Spikes and prototypes you intend to delete.
One off scripts: a data migration you run once, a quick scraper, a throwaway chart.
Demos and hackathon code where shipping in an hour beats shipping correctly.
Exploratory work where the spec would just be a guess anyway.
Personal tools with exactly one user who is also the author.

The common thread is that nobody inherits the code. There is no future maintainer, no on call engineer, no agent that has to extend it next week. When the blast radius of a mistake is your own afternoon, the overhead of a spec is not worth it. Vibe away.

What spec-driven development actually is

Spec-driven development inverts the order. You write the specification first, then the code exists to satisfy it. The spec is not a wishlist. It is goals (what to build and why), constraints (the stack, the boundaries, what is out of scope), and verifiable acceptance criteria (conditions something can check by running a command and reading the output).

The phases come from GitHub Spec Kit: specify the intent, plan the approach, break it into tasks, then implement and verify. Each phase produces an artifact the next phase consumes. The full version of this workflow, with PRDs, task lists, and breakdown, is laid out in spec-driven development with AI.

The defining property is that “done” is not a feeling. A spec-driven task is done when a specific, checkable condition is true. “Login works” is a vibe. “POST /api/login with a wrong password returns 401 and the body { error: 'Invalid credentials' }” is a criterion a machine can confirm without your opinion. That single difference is what makes the rest of this comparison fall out.

Why an autonomous agent needs a spec

Here is the part that decides the whole debate for anyone running agents in a loop. A human can vibe code because a human carries the unwritten spec. You know the system. You remember the edge case from last month. You ask a teammate when something is ambiguous. An autonomous agent does none of that.

An agent reads what is on disk. When the spec is silent, it does not pause and ask. It invents an answer and proceeds with full confidence. The guess looks fine in the diff and breaks on the case nobody wrote down. Multiply that across a long run and you get a pile of confident, untested code that drifts further from your intent on every iteration.

The Ralph technique makes this concrete. Each iteration starts the agent with a fresh context window, which is what keeps a long run from rotting (the agent losing the plot over a marathon session). The mechanics are covered in what is the Ralph technique, the loop popularized by Geoffrey Huntley in his original Ralph writeup. Fresh context is the reason the loop survives. It is also the reason vibe coding cannot drive it.

Think about what fresh context implies. The agent that starts iteration 30 has no memory of the conversation from iterations 1 through 29. It rebuilds its entire understanding from files: the PRD, the task list, the logs, the git history. There is no “you know what I meant” to fall back on. If the intent is not written down, it does not exist for that iteration’s agent.

So the loop needs the spec for two reasons:

No guessing. Written goals and constraints mean the fresh-context agent reorients to the same target every pass instead of inventing a new one.
A stop condition. The loop ends on an explicit completion signal, not a vibe. The agent emits <promise>COMPLETE</promise> when every task passes its criteria, and ralph.sh exits with code 0. Without verifiable criteria there is nothing for the loop to check, so it can never honestly say it is done.

That is the core argument. You cannot run an agent unattended against “make it good.” You can run it against a task list where every task carries acceptance criteria the verification stack can confirm.

What vibe coding costs at scale

Vibe coding feels free because the cost is deferred. It shows up later, somewhere else, and usually larger. Three costs dominate once the work outgrows a single afternoon.

Rework. Code accepted on a vibe gets rejected on a test you write three weeks later, or worse, by an incident. The fix is rarely a one line change, because the original code encoded a misunderstanding, not a typo. You are not patching a bug. You are re-deriving the requirement that was never written down, then rewriting against it. Specifying first front-loads that thinking when it is cheap.

Drift. Every implicit decision is a decision someone, or some agent, makes for you. Vibe coding scatters those decisions across files and weeks. One place validates email with a regex, another with a library, a third not at all. There was never a source of truth, so the codebase has three answers to one question. With a spec, the answer is written once and every task inherits it.

Unverifiable output. This is the expensive one for AI workflows. If you cannot state how to check that the work is correct, you cannot automate the check, which means a person has to read every diff and judge it by hand. That person becomes the bottleneck. The whole promise of an autonomous loop is that the machine verifies its own work. Vibe coding removes the thing the machine would verify against, so you are back to manual review at the exact moment you wanted to step away.

The repo mantra is blunt: if you didn’t test it, it doesn’t work. Vibe coding at scale is a bet that you will remember every unwritten assumption and that nobody else will touch the code. Both halves of that bet lose over time.

How to pick per task

The honest answer is that you do not pick one approach for your whole life. You pick per task, and the deciding questions are quick.

flowchart TD
  Start["New piece of work"] --> Survive{"Does the code survive past today?"}
  Survive -->|"No, it is a spike or demo"| Vibe["Vibe code it, delete it later"]
  Survive -->|"Yes"| Criteria{"Can you write pass or fail acceptance criteria?"}
  Criteria -->|"Not yet, too fuzzy"| Spike["Vibe a spike first, then spec what you learned"]
  Criteria -->|"Yes"| Agent{"Will an autonomous agent build it unattended?"}
  Agent -->|"No, you are at the keyboard"| Mixed["Spec the risky parts, vibe the glue"]
  Agent -->|"Yes"| Spec["Spec-driven: PRD, tasks, criteria, verify"]

Walk the branches:

Does it survive past today? If the answer is no, stop reading and vibe it. A migration script you run once does not need a PRD.
Can you write pass or fail criteria? If the problem is still fuzzy, you do not know enough to spec well. Vibe a spike to learn the shape, then write the spec from what you learned. The spike was reconnaissance, not the deliverable.
Will an agent build it unattended? This is the hard cutoff. The moment a fresh-context agent is doing the work without you watching, you need the spec. There is no in between, because the agent has no judgment to fall back on and no way to ask you mid-iteration.
You at the keyboard, code that survives? This is the common case, and it is mixed. Spec the parts where a wrong guess is expensive (auth, money, data integrity, public APIs). Vibe the glue where a mistake is cheap and obvious. You do not need acceptance criteria for a button’s hover color.

The mistake is treating this as ideology. Spec-driven purists waste hours writing criteria for code they will delete. Vibe coding diehards ship confident nonsense to production. The discipline is matching the rigor to the stakes.

How Ralph leans spec-driven

Ralph is built for the unattended case, so it leans spec-driven by design. It does not force you to write a PRD for a one line fix, but the loop architecture assumes a spec exists when you run it for real.

The spec lives in two files under .agent/prd/. PRD.md is the full document: goals, constraints, core features, technical stack, security considerations, and assumptions. SUMMARY.md is the short executive overview sent to the agent every iteration so it reorients fast without rereading the entire PRD. Long document for depth, short summary for the working context on each pass.

You do not write all of this by hand. The prd-creator skill, run in plan mode, interviews you one question at a time, researches the problem, and writes both files plus a task list. The details of writing that document, and acceptance criteria an agent can actually verify, are in how to write a PRD an AI agent can actually build from.

The PRD then decomposes into a task lookup table. tasks.json holds the list, and each tasks/TASK-{ID}.json carries its own description, dependencies, and an acceptanceCriteria array. This is the structure that lets a loop grind through hundreds of tasks without losing track, covered in task lookup tables for agents.

npx @pageai/ralph-loop
./ralph.sh -n 50

Each iteration the loop finds the highest-priority incomplete task, works its steps, runs tests and linting and type checking, takes a screenshot, flips the task to passing only when the gate is green, and commits. The verification stack is Playwright, Vitest, TypeScript, ESLint, and Prettier. The agent does not get to declare victory on a vibe. It declares victory when the criteria pass, and the loop stops on the completion promise.

That is the whole point of the comparison in one workflow. The spec is what lets the machine verify its own output, which is what lets you close the laptop. Vibe coding is the right tool when nobody inherits the code. The moment an agent inherits it, the spec stops being overhead and starts being the only thing keeping the loop honest.

Where to go next

If you are deciding how much structure a piece of work deserves, read across the spec-driven cluster:

Spec-driven development with AI for the full Specify, Plan, Tasks, Implement workflow.
How to write a PRD an AI agent can actually build from for the document that sits at the top of it.
Task lookup tables for agents for scaling a spec to hundreds of tasks.

For the loop that reads your spec on every pass and why fresh context changes the rules, read what is the Ralph technique.

Frequently asked questions

What is the difference between spec-driven development and vibe coding?

Vibe coding writes code by feel: you prompt with loose intent, read the output, and accept it because it looks plausible and runs. Spec-driven development writes the specification first, so the code exists to satisfy concrete goals, explicit constraints, and verifiable acceptance criteria. The defining difference is whether done is a feeling or a checkable condition a machine can confirm by running a command and reading the output.

Is vibe coding ever the right choice?

Yes, when the code is disposable and nobody inherits it. Spikes you intend to delete, one off scripts, demos, hackathon code, and personal tools with one user are all fine to vibe. The overhead of a spec is not worth it when the blast radius of a mistake is your own afternoon. Vibe a spike to learn a fuzzy problem, then write the spec from what you learned.

Why do autonomous AI agents need a spec instead of vibe coding?

An autonomous agent reads only what is on disk, and a Ralph loop starts each iteration with a fresh context window that has no memory of previous iterations. When the spec is silent, the agent invents an answer and proceeds with full confidence, and that guess compounds across a long run. Verifiable acceptance criteria give the loop something to check and a real stop condition, so it can honestly signal completion instead of guessing it is done.

What does vibe coding cost once a project scales?

Three things: rework, because code accepted on a vibe encodes a misunderstanding you later re-derive and rewrite; drift, because every implicit decision gets answered differently across files with no source of truth; and unverifiable output, because if you cannot state how to check correctness, a person has to read every diff by hand. That manual review is the exact bottleneck an autonomous loop is supposed to remove.

How does Ralph use spec-driven development?

Ralph keeps the spec in .agent/prd/PRD.md and a short SUMMARY.md sent to the agent each iteration, generated by the prd-creator skill in plan mode. The PRD decomposes into a task lookup table where each TASK-ID.json carries acceptance criteria. Every iteration the loop works one task, runs Playwright, Vitest, TypeScript, ESLint, and Prettier, and only marks the task passing when the gate is green, then commits and stops on a completion promise.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

Docker Sandboxes vs Plain Containers for AI Agents

Tue, 05 May 2026 00:00:00 GMT

A plain container is a start, not a boundary. Running an autonomous coding agent inside docker run does isolate it from your host filesystem, which is already better than running the agent directly on your laptop. The gap is that a normal container shares your host kernel, so the wall between an agent executing arbitrary shell commands and your machine is thinner than most people assume. Docker Sandboxes close that gap by giving each sandbox its own microVM with a separate guest kernel, which is the difference this post is about when you compare a docker sandbox vs container ai agent setup.

If you want the full safety argument first, the pillar guide on how to run AI coding agents in Docker Sandboxes safely covers the whole boundary. This post zooms in on one question: what does a hand-rolled container actually give you, where does it leak, and why does a microVM hold where a container does not.

Container vs sandbox, the short answer

The decision comes down to what you are isolating from and how much you trust the workload.

A container is the right tool for software you trust. You built it, you reviewed it, and you are shipping it. Namespaces and cgroups keep processes tidy and resource bounded, and the shared kernel is a feature because it is fast and cheap.

A microVM is the right tool for software you explicitly do not trust to behave. An autonomous agent running in bypass-permissions mode is exactly that. It decides which commands to run, it can curl | bash something it found in a README, and it does not have an undo. For that workload you want a virtualization boundary, not just a kernel namespace.

So the short answer: use a container when the code is yours and reviewed, use a sandbox when a probabilistic system is executing shell commands on your behalf. The rest of this post is the detail behind that rule.

What a hand-rolled container actually gives you

Start with the honest version of the container story, because containers are useful and a docker run is genuinely a step up from nothing.

A container gives the agent its own process namespace, its own mount namespace, its own network namespace, and a cgroup that can cap CPU and memory. The agent sees its own process tree, not yours. It sees the filesystem you mounted, not your whole home directory by default. That isolation is real, and for a lot of workloads it is enough.

Here is a minimal version of what people reach for first:

docker run -it --rm \
  -v "$PWD":/work -w /work \
  node:22 bash

This drops you into a container with your project mounted at /work. The agent can edit those files, run installs, and run tests. Your ~/.ssh and ~/.aws are not mounted, so they are not visible. For a quick experiment that is a reasonable boundary.

The problem is that the defaults of a plain container were designed for running trusted software conveniently, not for caging an untrusted process. So the moment you run a real agent for hours, the soft spots start to matter.

Where the container leaks

There are four leaks worth naming, because each one is a place a long autonomous run can go wrong.

First, root by default. Unless you say otherwise, the process inside the container runs as root (uid 0). It is namespaced root, not host root, but it is still root inside the container, which widens what a container escape or a misconfigured mount can reach. An agent that runs chmod, chown, or installs system packages as root is one surprised step closer to your host than it needs to be.

Second, the shared kernel. This is the big one. Every container on the machine, including the agent’s, talks to the same host kernel you are using. Namespaces are a kernel feature isolating a process from other processes, not a separate operating system. A kernel level bug, a privileged syscall, or a known container escape has your actual kernel as its target. You are trusting the kernel boundary to hold against code you specifically decided not to trust.

Third, bind mounts. The convenient -v "$PWD":/work is a two way door. The agent writes to your real working tree on the host, which is the point, but it also means a bad rm -rf or an overzealous “let me clean this up” reaches your real files, not a copy. People also tend to mount more than they should over time (a config directory here, a credentials file there) and each added mount is another path out of the box. Mounting the Docker socket (/var/run/docker.sock) is the worst case, because a process that can talk to the Docker daemon can start a new container as host root and own the machine.

Fourth, the network. By default a container gets full outbound network access through the default bridge. An agent with unrestricted egress can fetch arbitrary code and, in the worst case, send data out. There is no allowlist unless you build one, and building one with raw containers means writing firewall rules by hand.

None of these are reasons to never use a container. They are reasons to not assume docker run is a security boundary for an untrusted agent. For the broader case on why every autonomous run needs a wall around it, see why you should sandbox every autonomous coding agent.

How Docker Sandboxes differ

Docker Sandboxes (the sbx CLI) are built for the untrusted workload case, and the Docker Sandboxes documentation is the primary source for the internals. Three differences matter most for agents.

A microVM per sandbox

Each sandbox runs inside its own lightweight virtual machine with its own guest kernel, not a namespaced process sharing your host kernel. That single change is what upgrades the boundary from “trust the kernel namespace” to “defeat a virtualization layer.” A process that escapes the agent’s view inside the sandbox lands in a guest kernel that is not your kernel, with a virtual machine monitor between it and your host.

For the agent this is invisible. It still gets a Linux environment, a shell, a filesystem, and the tools it expects. The isolation is underneath, where the agent cannot see it and does not need to.

flowchart TB
  subgraph PlainPath["Plain container"]
    direction TB
    PApp["Agent process, often root"]
    PNS["Namespaces + cgroups"]
    PKernel["Shared host kernel"]
    PHost["Host: files, keys, network"]
    PApp --> PNS --> PKernel --> PHost
  end
  subgraph SbxPath["Docker Sandbox (sbx)"]
    direction TB
    SApp["Agent process in YOLO mode"]
    SGuest["Guest kernel (microVM)"]
    SVMM["Virtual machine monitor"]
    SHost["Host: isolated, project dir shared only"]
    SApp --> SGuest --> SVMM --> SHost
  end

Read the two stacks top to bottom. In the plain container, the agent process reaches the host across one shared kernel. In the sandbox, the agent process reaches the host only after getting through a guest kernel and a virtual machine monitor, and the host shares nothing but the one project directory you pointed it at.

Standalone, no Docker Desktop, seconds to spin up

Docker Sandboxes run as a standalone CLI. You do not need Docker Desktop running to use sbx, which keeps the dependency surface small and makes it easy to script. A sandbox spins up in seconds, so the microVM is not a heavy thing you provision once and babysit. It is closer to the ergonomics of docker run: you ask for it, you get it quickly, you throw it away when you are done.

That speed matters for a loop. A tool like Ralph Loop creates or reattaches a sandbox on every iteration, so a slow boundary would tax every pass. Fast startup is what makes “isolate every run” practical instead of aspirational.

Deterministic names and a network gate

Two more things come for free with the sandbox model that you would otherwise build by hand.

Sandboxes get deterministic names so the same project and agent pair reuses the same microVM. Ralph uses the form ralph-<agent>-<current-dir>-<hash8>, for example ralph-claude-my-app-a1b2c3d4. You list them with sbx ls, shell into one with sbx exec -it <name> bash, and reattach with sbx run <name>. No tracking container IDs by hand.

The network is a gate, not an open door. Docker Sandboxes default to deny-by-default egress, and you allowlist exactly what a task needs:

sbx policy allow network ralph-claude-my-app-a1b2c3d4 "*.npmjs.org,github.com"

You can apply a rule globally with -g, and the "**" pattern opens a single sandbox fully when you genuinely cannot enumerate the domains. The full treatment of building an allowlist that lets installs through while keeping exfiltration out lives in network policies for AI agent sandboxes. The point versus a plain container: you get this gate without writing iptables rules.

If you must use a plain container, harden it

Sometimes a microVM is not available in your environment and a container is what you have. You can close most of the obvious leaks with flags. This will not give you a separate kernel, so it is not equivalent to a microVM, but it is a real improvement over a naked docker run.

Run as a non-root user instead of root:

docker run --user 1000:1000 ...

Drop every Linux capability and add back only what you actually need:

docker run --cap-drop=ALL ...

Block privilege escalation so a setuid binary cannot regain capabilities:

docker run --security-opt=no-new-privileges ...

Make the root filesystem read-only and give the agent a scratch space that is not your host:

docker run --read-only --tmpfs /tmp ...

Cut the network entirely when a task does not need it, or attach a tightly scoped network when it does:

docker run --network none ...

Cap resources so a runaway loop cannot starve the host:

docker run --memory 4g --cpus 2 --pids-limit 512 ...

Put together, a hardened run looks like this:

docker run -it --rm \
  --user 1000:1000 \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --read-only --tmpfs /tmp \
  --memory 4g --cpus 2 --pids-limit 512 \
  --network none \
  -v "$PWD":/work -w /work \
  node:22 bash

Two things to keep in mind. Never mount the Docker socket into an agent container, because that hands the agent the daemon and therefore the host. And remember that all of this still rides on your shared kernel, so a kernel level escape defeats every flag above at once. Hardened containers raise the cost of an escape. A microVM changes what an escape even targets.

Why Ralph defaults to sbx

Ralph runs every agent inside a Docker Sandbox by default, and the reasoning is the whole post in one line: the sandbox is the boundary, so the agent is free to move fast inside it. Because the boundary is external and real, Ralph runs agents in bypass-permissions mode (Claude Code’s --dangerously-skip-permissions, with equivalents for other CLIs) without the usual dread. The danger of YOLO mode comes from the target on the host, and the microVM removes the target. The deeper version of that argument is in running agents in YOLO mode safely.

The loop wires the sandbox lifecycle so you never manage it by hand. Each iteration computes the deterministic name, checks that sbx exists, creates the sandbox on the first pass and attaches on later passes, runs the agent on exactly one task, and stops the sandbox through an exit trap when the run ends. The loop stops on an explicit completion promise (<promise>COMPLETE</promise>, <promise>BLOCKED:reason</promise>, or <promise>DECIDE:question</promise>), not on a vibe, and those map to exit codes 0, 2, and 3 with 1 reserved for hitting the iteration cap.

Starting a run is the same regardless of which agent you pick:

./ralph.sh -n 50
./ralph.sh --agent codex -- --model gpt-5.5

Supported agents are claude (the default), codex, copilot, cursor, gemini, and opencode. For the field guide on which CLI behaves best inside a long sandboxed loop, the agentic coding CLIs pillar is the cross-hub companion to this one. The takeaway stands on its own: a plain container is where you start, and a per-sandbox microVM is the boundary you actually want around an autonomous agent.

Frequently asked questions

Is a Docker container enough to sandbox an AI coding agent?

A plain container is a start, not a full boundary. It isolates the process and the filesystem you mount, which is better than running the agent on the host, but it shares your host kernel, often runs as root, and has open outbound network by default. For an untrusted agent running arbitrary commands, a microVM that gives each sandbox its own guest kernel is a stronger boundary.

What is the difference between a Docker Sandbox and a plain Docker container?

A plain container shares the host kernel and isolates processes with namespaces and cgroups. A Docker Sandbox, run with the sbx CLI, gives each sandbox its own lightweight virtual machine with a separate guest kernel and a virtual machine monitor between it and the host. The sandbox also defaults to deny-by-default network egress, which a plain container does not.

Where does a hand-rolled container leak when running an agent?

Four common places: the process runs as root by default, the container shares your host kernel so a kernel level escape reaches your machine, bind mounts write straight to your real files and can expose more than intended, and the default network gives the agent full outbound access. Mounting the Docker socket is the worst case because it hands the agent control of the host.

How can I harden a plain container if I cannot use a microVM?

Run as a non-root user, drop all capabilities with cap-drop ALL, set no-new-privileges, make the root filesystem read-only with a tmpfs scratch space, cap memory, CPU, and pids, and restrict the network. Never mount the Docker socket. These flags raise the cost of an escape but still rely on the shared kernel, so they are weaker than a separate guest kernel.

Why does Ralph default to Docker Sandboxes instead of plain containers?

Because the sandbox is the boundary that makes bypass-permissions mode safe. The microVM removes the target an agent could hit on the host, so the agent can run fast and autonomously while the worst case stays contained. Ralph also automates the lifecycle, computing a deterministic sandbox name and creating, attaching, and stopping the sandbox across loop iterations.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

Task Lookup Tables: Scaling Autonomous Agents to Hundreds of Tasks

Thu, 30 Apr 2026 00:00:00 GMT

A flat task list does not scale. Once you push past a few dozen entries, a single file that holds every task plus every step, criterion, and note becomes too big to load into an agent’s context window on every iteration. The fix is a task lookup table: a lean index of tasks that points to a separate detailed spec file per task. The agent reads the small index to decide what to do next, then loads exactly one spec file to do it. That separation is what lets an autonomous loop work through hundreds of tasks without choking on its own backlog.

This post shows how Ralph models that pattern with .agent/tasks.json and .agent/tasks/TASK-{ID}.json, why the split scales, how status and priority selection work each iteration, and how you grow the table over time. It assumes you already understand spec-driven development with AI and want the data structure that makes a long run survivable.

What a task lookup table is

A lookup table is an index. Instead of one giant document that mixes the list of work with the detail of each item, you keep two layers.

The first layer is a flat array where each entry is small: an id, a title, a category, a pointer to the detail file, and a status flag. That is the lookup table. It answers one question fast: what is left to do, and which thing is next.

The second layer is one spec file per task. Each file is the full contract for a single unit of work: description, acceptance criteria, ordered steps, dependencies, complexity, and technical notes. The agent only opens this when it has already decided to work that task.

The reason to split is the same reason a database keeps an index separate from the rows. You scan the cheap thing to find the right record, then you read the expensive thing once. An agent that has to load 200 fully detailed tasks just to pick the next one burns its context window before it writes a line of code.

How Ralph models it: tasks.json plus per-task specs

Ralph keeps the index in .agent/tasks.json and the detail in .agent/tasks/TASK-{ID}.json. The root file is deliberately thin. Each entry carries only what the loop needs to choose a task.

[
  {
    "id": "TASK-1",
    "title": "Verify project prerequisites and access",
    "category": "setup",
    "specFilePath": ".agent/tasks/TASK-1.json",
    "passes": false
  },
  {
    "id": "TASK-2",
    "title": "User table with authentication fields",
    "category": "data-model",
    "specFilePath": ".agent/tasks/TASK-2.json",
    "passes": false
  },
  {
    "id": "TASK-3",
    "title": "POST /api/auth/register creates new user account",
    "category": "api-endpoint",
    "specFilePath": ".agent/tasks/TASK-3.json",
    "passes": false
  }
]

Five fields, nothing more. The specFilePath is the pointer that turns this flat list into a lookup table. The passes flag is the status. Everything heavy lives behind the pointer, in the per-task file.

Here is what one of those spec files holds. This is TASK-3.json, the detail behind the one-line index entry above.

{
  "id": "TASK-3",
  "title": "POST /api/auth/register creates new user account",
  "category": "api-endpoint",
  "description": "Validate input, hash the password, store the user, and return a success response.",
  "acceptanceCriteria": [
    "POST with a valid email and password returns 201 with the user id and email",
    "Invalid email format returns 400 with the error text Please enter a valid email",
    "Password shorter than 8 characters returns 400",
    "Duplicate email returns 409, not a generic 500",
    "The stored password starts with $2b$ and is never the plaintext value"
  ],
  "steps": [
    {
      "step": 1,
      "description": "Add the register route handler",
      "details": "Validate with a zod schema, hash with bcrypt, insert into the users table.",
      "pass": false
    },
    {
      "step": 2,
      "description": "Write Vitest cases for every acceptance criterion",
      "details": "Cover valid registration, invalid email, short password, duplicate email, and the stored hash prefix.",
      "pass": false
    }
  ],
  "dependencies": ["TASK-1", "TASK-2"],
  "estimatedComplexity": "medium",
  "technicalNotes": [
    "Never log passwords, even in error branches",
    "Return 409 on duplicate email rather than a generic 500"
  ]
}

Notice the asymmetry. The index entry for TASK-3 is five lines. The spec file is forty. Multiply that across a real project and the savings are obvious: a 200 task project has a tasks.json of roughly a thousand lines of thin entries, while the detail sits in 200 separate files the agent never loads all at once.

The diagram below is the whole idea. The loop scans the lean table, picks one id, follows its specFilePath, and loads only that file into the working context.

flowchart LR
  Index["tasks.json: lean index, one line per task"]
  Index --> Scan["Scan for highest-priority task where passes is false"]
  Scan --> Pick["Selected: TASK-3"]
  Pick --> Path["Follow specFilePath"]
  Path --> Spec["tasks/TASK-3.json: full spec loaded into context"]
  Spec --> Work["Work the steps, run the gate"]
  Work --> Flip["Set passes true in tasks.json, commit"]
  Index -. "not loaded" .-> Rest["tasks/TASK-4.json ... TASK-200.json"]

The dotted edge is the point. Every other spec file stays on disk, unread, until its turn comes. The agent never pays the token cost of a task it is not working.

Why this scales to hundreds of tasks

The scaling property comes from one fact: the agent only loads the one task it needs. Every iteration of the Ralph loop starts the agent with a fresh context window. It does not carry the previous iteration in chat history. It rebuilds its understanding from files. So the cost of each iteration is whatever the agent reads off disk, not the size of the whole project.

Walk through the math. Suppose the average per-task spec is 40 lines and the project has 200 tasks. If the agent had to load every detailed task to orient itself, that is 8000 lines on every single iteration, repeated 200 times. With a lookup table, each iteration loads the thin index (around 1000 lines of one-line entries) plus exactly one spec file (40 lines). The detail you load grows by one file, not by the entire backlog, no matter how large the table gets.

That is why a flat, fully detailed task file hits a wall. It works fine at ten tasks. At a hundred it crowds out the actual code in the context window, and the agent starts skimming, missing acceptance criteria, and contradicting earlier decisions. Splitting the index from the detail keeps the working context flat as the project grows.

The token economics reinforce this. Tokens in the context window cost money and attention on every pass. You do not want to spend that budget reloading 199 tasks the agent will not touch this iteration. A lean index plus one spec is the minimum the agent needs to choose work and do it correctly. This is the same instinct behind keeping a short SUMMARY.md for the PRD instead of resending the full document every iteration: load the index constantly, load the detail on demand.

Status tracking with the passes flag

Status lives in two places, and the split mirrors the index-and-detail structure.

At the index level, each entry in tasks.json has a single passes boolean. It starts false. The agent only flips it to true after the work is built and verified. The loop reads this flag to decide what is finished and what remains. Scanning for incomplete work is a pass over the lean index, which stays cheap even at hundreds of entries.

At the detail level, each step inside a spec file has its own pass boolean. These track progress within a single task: step one done, step two not yet. A task is not complete until every step passes and the acceptance criteria hold. Only then does the top-level passes in the index flip.

The rule that protects this system is strict: never flip passes to true until the work is verified. Tasks are generated with passes: false and stay false until the agent runs the verification stack the loop assumes, which is Playwright for end to end, Vitest for unit tests, TypeScript for types, ESLint for lint, and Prettier for format. The repo mantra is blunt: if you didn’t test it, it doesn’t work. A status flag that flips on a vibe instead of a passing gate turns the lookup table into a lie, and a fresh-context agent will trust that lie on the next iteration.

Because status is just a flag in a file, the run is resumable and auditable. Any fresh agent on any machine can read tasks.json, see which entries are still false, and pick up exactly where the last one stopped. Watching those flags flip across a run, alongside the per-iteration history and screenshots, is the basis of observability for autonomous coding agents. The table is both the work queue and the progress report.

Priority selection each iteration

Picking the next task is a scan over the index, and the order is not arbitrary. Each iteration, the loop finds the highest-priority incomplete task in tasks.json, then loads that one spec file and works its steps.

Two things shape the selection.

First, dependencies. Each spec file carries a dependencies array of task ids that must finish before it can start. TASK-3 (the register endpoint) lists ["TASK-1", "TASK-2"], so the loop will not select it until the prerequisite gate and the users table are both passes: true. The agent never builds on a foundation that is not there yet.

Second, the prerequisite gate. TASK-1 is always reserved for prerequisite verification: environment variable placeholders exist, database access works, required tools are authenticated, and any open gaps have an explicit proceed or block decision. Every downstream task that needs those prerequisites lists TASK-1 as a dependency. You do not want an agent discovering halfway through a 200 task run that it never had database credentials.

flowchart TD
  Start["Fresh context"] --> Read["Read tasks.json index"]
  Read --> Filter["Filter to passes false"]
  Filter --> Deps{"Dependencies satisfied?"}
  Deps -->|"no, skip"| Next["Try next candidate"]
  Next --> Deps
  Deps -->|"yes"| Select["Select highest-priority task"]
  Select --> Load["Load its TASK-ID.json spec"]
  Load --> Build["Work the steps"]
  Build --> Gate["Tests, lint, types, screenshot"]
  Gate -->|"fail"| Build
  Gate -->|"pass"| Update["Set passes true, commit"]
  Update --> Stop["Stop. Next iteration starts clean"]

The loop completes exactly one task per invocation, commits, and stops. It never batches. That discipline is what keeps a long run reliable, and the reasoning behind it is covered in one task per iteration. The lookup table is what makes one-task-per-iteration cheap to execute: selection is a quick scan of flags and dependencies, not a re-read of the entire project.

You control how many of these iterations run. The default is 10. Run more with a flag.

npx @pageai/ralph-loop
./ralph.sh -n 50

If the table has 200 tasks and you cap the loop at 50 iterations, the run stops at the cap with exit code 1 (MAX_ITERATIONS) and the remaining tasks stay false in the index, ready for the next run to resume. Nothing is lost. The lookup table is the durable record.

Adding tasks over time with the prd-creator skill

A lookup table is not a frozen document. You grow it as the project grows, and you do not hand-edit a 200 entry JSON file to do that.

Ralph ships a prd-creator skill that turns unstructured requirements into a PRD plus a task list. The first time you run it, it interviews you, writes .agent/prd/PRD.md and .agent/prd/SUMMARY.md, then generates tasks.json with one TASK-{ID}.json spec per task. TASK-1 is always the prerequisite gate, and every task is initialized with passes: false. For a typical project that is dozens to hundreds of entries, not five, because the skill keeps tasks small: anything too complex to finish in a short sitting gets split.

When you want to add a feature or fix a bug later, you run the skill again. It updates the PRD and appends new tasks to the index, each with its own spec file, each starting false. The completed entries keep their passes: true status, so the loop ignores them and works only the new false ones. The table grows without disturbing the finished work.

Use the prd-creator skill in plan mode. Add a password reset flow to the
existing PRD and append the new tasks to .agent/tasks.json with one spec
file each under .agent/tasks/.

Run it in plan mode, where the agent is read-only and asks questions instead of writing code. The skill decomposes the new feature into atomic tasks the same way it did the first batch, which is its own discipline covered in breaking a PRD into atomic agent tasks. The result is a lookup table that accretes work over the life of the project while staying scannable, because the index entries stay thin no matter how many you add.

Where to go next

If you are building the spec that drives a long run, read across the spec-driven cluster:

Spec-driven development with AI for the full Specify, Plan, Tasks, Implement workflow the lookup table sits inside.
Breaking a PRD into atomic agent tasks for decomposing work into the packets that fill the table.
One task per iteration for the rule that makes the lookup table cheap to execute.

For watching the table fill in across a run, with logs, history, and screenshots, read observability for autonomous coding agents.

Frequently asked questions

What is a task lookup table for an AI agent?

It is a two-layer structure that separates the list of work from the detail of each item. The first layer is a lean index where each entry has an id, title, category, a pointer to a detail file, and a status flag. The second layer is one spec file per task with the full description, acceptance criteria, steps, and dependencies. The agent scans the cheap index to pick the next task, then loads only that one spec file to do the work.

Why does a flat task list stop scaling for autonomous agents?

A flat list that holds every task plus all of its detail gets too large to load into the context window on every iteration. At ten tasks it is fine. At a hundred it crowds out the actual code, so the agent skims, misses acceptance criteria, and contradicts earlier decisions. A lookup table keeps the working context flat because each iteration loads the thin index plus exactly one detailed spec, no matter how many tasks exist.

How does Ralph store tasks on disk?

The index is .agent/tasks.json, a flat array where each entry has id, title, category, specFilePath, and a passes flag. The detail for each task lives in .agent/tasks/TASK-{ID}.json with description, acceptance criteria, ordered steps, dependencies, estimated complexity, and technical notes. The agent reads these files fresh on every iteration, so the filesystem is the memory rather than the chat history.

How does the agent choose which task to work next?

Each iteration it scans tasks.json for the highest-priority entry where passes is false and whose dependencies are already satisfied. TASK-1 is always prerequisite verification, and downstream tasks list it as a dependency, so feature work never starts before access and environment are confirmed. The agent loads that one spec file, works the steps, runs the verification gate, then flips passes to true and commits.

How do I add more tasks to the lookup table over time?

Run the prd-creator skill again in plan mode. It updates the PRD and appends new tasks to tasks.json, each with its own spec file under .agent/tasks/ and each initialized with passes set to false. Completed entries keep their passes true status, so the loop ignores them and works only the new false ones. The table grows without disturbing finished work and stays scannable because the index entries stay thin.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

Why You Should Sandbox Every Autonomous Coding Agent

Sat, 25 Apr 2026 00:00:00 GMT

Sandbox every autonomous coding agent because the agent runs with your permissions. When you start an agent on your laptop, it does not run as some restricted service account. It runs as you, with your user, which means it can read your SSH keys, your cloud credentials, and your full git history, and it can execute any shell command those permissions allow. A sandbox moves all of that out of reach, so the worst case becomes a throwaway environment you reset instead of a credential leak you cannot undo. That is the entire argument for why sandbox ai agent work, and the rest of this post is the detail behind it.

An agent runs as you, with everything you can touch

Think about what your own user account can do on a normal dev machine. You can read ~/.ssh/id_ed25519, the private key that authenticates you to GitHub and every server you SSH into. You can read ~/.aws/credentials, ~/.config/gh/hosts.yml, .env files scattered across projects, and the browser session cookies sitting in your home directory. You can git push --force, delete directories, and run a curl | bash line you copied from a README.

An autonomous agent inherits all of it. The model is not malicious. It is a probabilistic system that emits shell commands, and shell commands do not ask for intent. When the agent decides to “clean up some old files” or “reset the environment to a known state,” there is no separate permission layer protecting your home directory. The agent is you, and you have access to everything.

This is fine when a human drives each command and reviews it. Autonomy removes the human from that loop on purpose. The whole point of a Ralph-style loop is that the agent works for hours without you watching, picking up the next task in .agent/tasks.json, running commands, and committing. The thing that made interactive use safe (you reading each command before approving it) is exactly the thing autonomy deletes.

So the question is not whether the agent will eventually run a command you would not have approved. Over a long enough run, it will. The question is what that command can reach when it does.

The blast radius problem with YOLO mode on your laptop

To run unattended, an agent has to stop asking permission. In Claude Code that switch is --dangerously-skip-permissions (also --permission-mode bypassPermissions, documented in the Claude Code docs). Other CLIs ship their own version of the same idea, usually called YOLO mode. The naming is honest. You are telling the agent to execute whatever it decides, with no confirmation, for the entire run.

On your host that is a genuinely bad idea, and the danger scales with the length of the run. One iteration is a handful of commands. A fifty-iteration overnight run is hundreds of commands, each one a chance for a hallucinated path, a destructive cleanup, or a misread instruction. You will not be awake to catch the one that matters.

The damage is not limited to the project either. Because the agent runs as you, a single bad command can reach far outside the directory you pointed it at:

It can read secrets from other projects and from your home directory, then paste them into a file, a log, or an outbound request.
It can push to remotes you have credentials for, including repositories that have nothing to do with the current task.
It can delete or rewrite files anywhere your user can write, with no undo.
It can install and execute arbitrary code pulled from the network.

None of these require the model to “go rogue.” They are the normal capabilities of your shell, exposed to a system running without a gate. Running bypass-permissions mode directly on a host is the failure mode, not a feature. For the safe version of that same flag, see running agents in YOLO mode safely.

flowchart LR
  subgraph NoSandbox["Without a sandbox: blast radius is your whole machine"]
    AgentA["Agent in YOLO mode (runs as you)"]
    AgentA --> Keys["SSH keys, cloud creds, cookies"]
    AgentA --> Repos["Every other git repo"]
    AgentA --> Net["Unrestricted network"]
    AgentA --> Proj1["Project directory"]
  end
  subgraph WithSandbox["With a sandbox: blast radius is one disposable microVM"]
    AgentB["Agent in YOLO mode (contained)"]
    AgentB --> Proj2["Project directory (only this)"]
    AgentB --> Gate["Network gate: deny-by-default"]
    AgentB -. "no path to" .-> HostKeys["Host keys and creds"]
    AgentB -. "no path to" .-> HostRepos["Other repos"]
  end

The two pictures use the same agent in the same mode. The only thing that changes is what “anything it can do” resolves to. On the left it resolves to your machine. On the right it resolves to a microVM you can throw away.

Why a sandbox makes autonomy acceptable

A sandbox does not make the agent trustworthy. It makes trust unnecessary. You stop trying to predict every command the model might emit and instead make the set of things any command can reach small and disposable. That inversion is what lets you walk away from a running agent and sleep.

Concretely, a sandbox shrinks the worst case from “the agent leaked my SSH key and force-pushed to a client repo” to “the agent trashed a throwaway environment, so I reset it and re-ran the loop.” The first outcome is a security incident. The second is a Tuesday. Same model, same flags, completely different cost when something goes wrong.

This is also why a sandbox is the precondition for real autonomy rather than a nice-to-have. Long unattended runs are the entire premise of running an AI coding agent overnight, and you cannot responsibly leave an agent running for hours unless the place it runs is one you can afford to lose. The sandbox is what makes the overnight run a reasonable decision instead of a gamble with your credentials.

There is a structural point underneath this. A permission prompt is not a security boundary, it is a question. The only real boundary is one enforced from outside the agent, by something the agent cannot reach through or talk its way around. A sandbox is that external boundary. The full version of this argument lives in the pillar guide, how to run AI coding agents in Docker Sandboxes safely.

How Ralph uses Docker Sandboxes by default

Ralph does not bolt on isolation as an option you remember to enable. It runs every agent inside a Docker Sandbox by default, using the sbx CLI. Each agent gets a lightweight virtual machine with its own kernel, which is a stronger boundary than a namespaced process sharing your host kernel. The Docker Sandboxes documentation is the primary source for how the microVM works underneath.

You do not manage that lifecycle by hand. The script computes a deterministic sandbox name, checks that sbx is installed, decides whether to create or attach, runs the agent in bypass-permissions mode inside the microVM, and stops the sandbox when the run ends. Because the sandbox is the boundary, the agent is free to skip permission prompts and move fast inside it.

Installing and running looks like this:

npx @pageai/ralph-loop
./ralph.sh -n 50

The first command drops Ralph into your project. The second runs the loop for fifty iterations, each one starting the agent with a fresh context inside the sandbox. Pick a different agent and pass agent-specific flags after a -- separator:

./ralph.sh --agent codex -- --model gpt-5.5
./ralph.sh -a gemini -n 5 -- --model pro

Supported agents are claude (the default), codex, copilot, cursor, gemini, and opencode. The default iteration count is 10, and --once runs exactly one iteration.

The sandbox name is deterministic so the same project and agent pair always reuses the same microVM:

ralph-<agent>-<current-dir>-<hash8>

<agent> is the agent slug, <current-dir> is the sanitized basename of the project directory, and <hash8> is the first eight hex characters of a sha256 of the absolute project path. The path hash keeps two same-named directories on different paths from colliding. You never have to memorize the name, because Ralph prints it on startup and on demand:

./ralph.sh --print-name
./ralph.sh --print-name --agent codex

When the run ends, by normal exit, by a double Ctrl+C, or by any path that fires the exit trap, Ralph stops only the sandbox it started:

sbx stop ralph-claude-my-app-a1b2c3d4

Stopping is not deleting, so you can reattach later to inspect what the agent did, then remove it with sbx rm when you are finished.

What good isolation actually looks like

Not every “sandbox” is a real boundary. A bare container that bind-mounts your whole home directory and has open network is theater. Three properties separate isolation that holds from isolation that only looks like it does.

Mount only the project, nothing else

The agent should see the project directory and nothing above it. Ralph shares your project at the same absolute path it has on your host, so tooling, config, and lockfiles resolve identically, while the rest of your home directory stays outside. No SSH keys, no ~/.aws, no unrelated repositories, no shell history full of tokens. The blast radius becomes the project you pointed at, plus whatever network you explicitly allow.

The corollary matters: because the project is shared, the agent can absolutely wreck your working tree. The protection there is git, not the sandbox. Work on a branch and commit often. The sandbox protects everything outside the project, and version control protects the code inside it.

Ephemeral by design

The environment has to be cheap to destroy and recreate. If resetting a contaminated sandbox is a multi-hour chore, you will avoid resetting it, and a sandbox you never reset slowly turns back into a pet you are afraid to lose. Ralph leans on the deterministic name here: tear a sandbox down with sbx rm, and the next iteration simply probes, finds nothing, and creates a clean one. That re-probe each iteration is what makes a long run resilient to you poking at the sandbox by hand.

Network limited, not wide open

Filesystem isolation is half the boundary. The other half is the network, because an agent with unrestricted outbound access can fetch arbitrary code and, in the worst case, send data out. Docker Sandboxes default to blocking outbound HTTP and HTTPS, then you allowlist exactly what the task needs:

sbx policy allow network ralph-claude-my-app-a1b2c3d4 "*.npmjs.org,github.com"

The practical symptom of deny-by-default is that npm install fails or an API call is refused until you grant the domain. That is the gate doing its job. You open specific hosts, not everything. There is a full-open escape hatch with the "**" rule, and it is the right tool only when you genuinely cannot enumerate the domains and you accept the tradeoff for that one sandbox. Building a tight allowlist that lets installs through while keeping exfiltration out is its own topic, covered in network policies for AI agent sandboxes.

A plain container can satisfy some of this and miss the rest, which is why the kind of sandbox matters. For where a hand-rolled container leaks and where a microVM holds, read Docker Sandboxes vs plain containers for AI agents.

A quick test before you run an agent unsandboxed

If you are tempted to skip the sandbox for a “quick” autonomous run, ask one question: if this agent ran rm -rf ~ or piped the contents of ~/.ssh to a pastebin, what would it cost you? If the honest answer is “a rebuild and some annoyance,” you are already in a disposable environment and you are fine. If the answer involves rotating credentials, notifying anyone, or the phrase “client repository,” you need the boundary before you start the loop.

The reason to make this the default rather than a judgment call is that the judgment is the part autonomy removes. You are not going to evaluate the risk of each of the next four hundred commands. You evaluate the environment once, up front, and then let the agent be fearless inside it.

Where the boundary ends

A sandbox is a strong boundary and not a magic one. Two limits are worth stating so you do not over-trust the setup.

First, the shared project directory is genuinely shared. The agent can corrupt your working tree, and only git will save you. Branch and commit.

Second, whatever you allowlist is genuinely reachable. Grant a domain that accepts uploads and an agent could in principle send data there. Keep network grants minimal, specific, and reviewed, the same way you would treat firewall rules, and avoid the "**" rule except on purpose.

Inside those limits the model is simple and it holds. Enforce the boundary from the outside, give the agent a disposable place to be fearless, and let the loop run. The sandbox is the blast radius, so fast and autonomous becomes the same thing as contained.

Frequently asked questions

Why do I need to sandbox an AI coding agent at all?

An autonomous agent runs with your user permissions, so it can read your SSH keys, cloud credentials, and git history, push to your remotes, and delete files anywhere you can write. In autonomous mode there is no human reviewing each command, so over a long run the agent will eventually execute something you would not have approved. A sandbox limits what any command can reach to a disposable environment.

What is the worst case if I run an agent without a sandbox?

The worst case is a security incident rather than an inconvenience. A single bad command can leak credentials from your home directory, force-push to an unrelated repository, or delete files with no undo, because the agent has your full permissions. With a sandbox the same bad command only touches a throwaway microVM that you reset and re-run.

Is bypass-permissions or YOLO mode ever safe?

It is unsafe on your host and safe inside a sandbox. On the host, --dangerously-skip-permissions gives the agent full shell access with no confirmation. Inside a Docker Sandbox microVM the same flag only grants access to the shared project directory and an allowlisted network, so the danger has no target on your machine.

Does Ralph sandbox agents automatically?

Yes. Ralph runs every agent inside a Docker Sandbox by default using the sbx CLI. It computes a deterministic sandbox name, creates or attaches the microVM each iteration, runs the agent in bypass-permissions mode inside it, and stops the sandbox when the run ends.

What makes isolation good rather than just theater?

Good isolation mounts only the project directory and nothing above it, stays ephemeral so it is cheap to destroy and recreate, and limits the network to an allowlist instead of leaving it wide open. A microVM with its own kernel is a stronger boundary than a container that shares your host kernel, especially for code you do not trust to behave.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

One Task Per Iteration: The Rule That Makes Autonomous Agents Reliable

Tue, 21 Apr 2026 00:00:00 GMT

The most reliable rule for autonomous coding is also the most boring: one task per invocation, commit, then stop. Each iteration the agent picks the single highest-priority incomplete task, works it to done, verifies it, commits, and exits. It never batches two tasks into one run. Break that rule and a loop that should grind cleanly through fifty tasks turns into a branch full of half-finished, hard-to-review work.

This rule is the operational core of a Ralph loop, and it sits one level below the spec-driven development workflow that produces the task list in the first place. The spec decides what the agent builds. This rule decides how it builds it without losing the plot.

The rule: one task, one commit, one stop

Stated as plainly as it goes in the repo’s own AGENTS.md: one task per invocation. When working from .agent/tasks.json, the agent completes exactly one task, commits, and stops. It never batches multiple tasks.

That is the whole rule. Three verbs: complete, commit, stop. The reason it is worth a thousand words is that every instinct (yours and the model’s) pushes the other way. You have fifty tasks and an agent that can clearly do more than one. Letting it power through feels efficient. It is not. It is the fastest way to turn a clean autonomous run into a debugging session.

An iteration that follows the rule produces one self-contained unit of progress: a feature built, its tests passing, its types checked, and a single commit that maps to exactly one task in the list. The next iteration starts from a known-good state. That property, every iteration ends in a verified checkpoint, is what makes long runs survivable.

Why batching tasks wrecks an agent loop

Batching means telling the agent (or letting it decide) to knock out three or five tasks before it commits. It looks like a throughput win. In practice it degrades the run in three compounding ways.

Context bloat and context rot

A coding agent has a finite context window and finite attention inside it. The longer a single session runs, the more it fills with intermediate state: files it opened, tests it ran, dead ends it explored, decisions it half-remembers. This is context rot. The agent starts contradicting earlier choices, re-editing files it already finished, and forgetting which of the five tasks it was actually on.

One task per iteration keeps the working context small and on-topic. The agent reads the summary and the one spec it needs, builds the one thing, and exits before the window gets crowded. Batching does the opposite: it lets the context grow across multiple unrelated tasks, which is precisely the condition under which agents start producing confident nonsense. Context rot is one of the headline Ralph loop failure modes, and batching is the most direct route to it.

Half-finished work piles up

When an agent juggles several tasks at once, a failure on task four can leave tasks one through three in a partial state. It edited shared files, started a refactor it did not finish, and now nothing in the batch is cleanly done. You cannot ship any of it, and you cannot easily tell where the good work ends and the broken work begins.

One task per iteration makes failure local. If the agent cannot finish the current task, it emits a <promise>BLOCKED:reason</promise> and stops, and everything committed before that point is intact and verified. You lost one iteration, not five tasks of tangled progress.

Commits get impossible to verify

A commit that contains one task is reviewable. The diff maps to a single entry in tasks.json, the acceptance criteria for that task tell you what to check, and the tests in the diff prove it. A commit (or worse, a single giant commit) that contains five tasks is archaeology. You cannot bisect it, you cannot revert one piece of it, and you cannot read why any single change exists six months later.

Clean, atomic commits are not a nicety here. They are the audit trail that makes you trust a diff you did not write. Batching trades that trail for a vague sense of speed you do not actually get, because the review and rework cost lands on you in the morning.

Fresh context per iteration is why one task works

One task per iteration only makes sense because of the other half of the design: every iteration starts the agent with a fresh context window. The loop does not carry chat history forward. It reboots the agent’s understanding from files on disk each time.

This is the central idea of the Ralph technique, popularized by Geoffrey Huntley in his original Ralph writeup. The agent’s memory is not the conversation. It is the filesystem and the git history: .agent/tasks.json, the per-task specs, the logs, and the commits. Because state lives on disk, a fresh agent can reconstruct exactly where the project stands and pick up cleanly.

Fresh context and one-task scope are two sides of the same coin. Fresh context per iteration only helps if the unit of work fits inside one clean window, and one task is the unit sized to do that. Pair them and each iteration is crisp: clean slate in, one verified task out. Try to batch tasks on top of fresh context and you reintroduce the bloat that fresh context was meant to prevent.

flowchart TD
  Fresh["Fresh context window"] --> Read["Read SUMMARY.md and tasks.json"]
  Read --> Pick["Pick highest-priority incomplete task"]
  Pick --> Spec["Open one TASK-{ID}.json"]
  Spec --> Work["Work the steps for that one task"]
  Work --> Gate["Verify: tests, lint, types, screenshot"]
  Gate -->|"fail"| Work
  Gate -->|"pass"| Commit["Set passes true and commit one task"]
  Commit --> Stop["Stop. Iteration ends at a checkpoint"]
  Stop --> Next["Next iteration starts with fresh context"]
  Next --> Fresh

Read that diagram as a single lap. The only way out of a lap is a verified commit or an explicit stop signal. There is no path where the agent commits two tasks in one pass, because the lap ends the moment one task is done.

Clean commits are your checkpoints and rollback points

Treat each per-task commit as a save point in a game. When the agent finishes a task and commits, it records a state you can return to. If iteration twelve goes sideways, you do not lose the eleven good iterations before it. You reset to the last clean commit and keep the verified work.

This is why the commit is not optional and not deferred. The loop’s standard iteration ends by updating the task status, taking a screenshot for UI work, and committing in Conventional Commit format. One task, one commit, one checkpoint. The git log becomes a ledger of progress where each line is a unit you can read, verify, and if necessary revert in isolation.

Batching destroys this. A commit that bundles several tasks is a single, coarse save point. Revert it and you lose good work alongside the bad. Bisect it and every “bad” commit contains multiple changes, so you cannot pin the regression to one task. The granularity of your commits is the granularity of your recovery, and one task per commit is the finest useful grain.

There is a second benefit that matters for long runs. Because every checkpoint is verified before it is committed, the branch is always in a shippable-ish state between iterations. You can stop the loop at any point, after iteration three or after iteration thirty, and what you have is a set of completed, tested tasks rather than a half-built mess. That is what lets you run an agent overnight and trust the morning diff.

How Ralph enforces one task per iteration

The rule is not a suggestion the agent is free to ignore. It is wired into how the loop and the prompt work together.

The loop itself is a Bash script (ralph.sh) that runs the agent once per iteration. Each iteration follows the same shape:

Find the highest-priority incomplete task in .agent/tasks.json.
Work the ordered steps in .agent/tasks/TASK-{ID}.json.
Run tests, linting, and type checking.
Complete the task, take a screenshot, update task status, and commit.
Repeat until all tasks pass or the iteration cap is reached.

Step one is where scope gets enforced: the agent selects the highest-priority incomplete task, singular. The prompt sent each iteration tells the agent to complete that one task, commit, and stop rather than continuing to the next. Because the next iteration starts a brand new agent with fresh context, there is no natural way to “keep going” across tasks. The process boundary between iterations is the enforcement mechanism.

You control how many iterations run. The default is ten. Use the flag to set your own cap:

# Run up to 50 iterations (50 tasks, one per iteration)
./ralph.sh -n 50

# Run exactly one iteration to watch a single task closely
./ralph.sh --once

./ralph.sh --once is the cleanest demonstration of the rule. It runs a single iteration: one task, one commit, one stop. Use it the first time you point Ralph at a new task list, watch it complete exactly one task, review the commit, and only then turn it loose with a larger cap.

The loop does not stop on a feeling. It stops on an explicit signal. After the run, the agent emits a promise tag and the script maps it to an exit code:

<promise>COMPLETE</promise>         all tasks finished      exit 0
<promise>BLOCKED:reason</promise>   needs human help        exit 2
<promise>DECIDE:question</promise>  needs a decision        exit 3

If the loop hits its iteration cap before the list is finished, it exits with code 1 (MAX_ITERATIONS). Either way, every task that did complete completed on its own iteration, with its own verified commit. The completion signal is per-run; the one-task discipline is per-iteration.

What about tasks that are too small or too big?

The obvious objection: if the agent does only one task per iteration, the task had better be the right size. That is true, and it is why scoping happens before the loop ever runs, during breakdown.

If your tasks are too big, the agent runs out of room inside one iteration and you get half-finished work, the exact failure the rule was meant to prevent. The fix is not to relax the rule. It is to cut the task smaller. A good task is something an agent can finish in one short sitting, with its own acceptance criteria and its own verification. Getting tasks to that size is the subject of breaking a PRD into atomic agent tasks, and it is the prerequisite that makes one task per iteration practical.

If your tasks are too small, you simply burn an iteration on something trivial, which is cheap and harmless. The asymmetry matters: tasks that are slightly too small cost you a little time, tasks that are too big cost you a tangled branch. When in doubt, split.

The other piece is ordering. One task per iteration only flows smoothly if the highest-priority incomplete task is actually buildable right now, with its dependencies already satisfied. That is what the task lookup table manages. Each task declares its dependencies, and the loop respects them so it never tries to build the dashboard before the data exists. Scaling that ordering to hundreds of tasks is covered in task lookup tables for agents. Get the breakdown and the ordering right, and one task per iteration is not a constraint you fight. It is the rhythm the whole run settles into.

Where to go next

One task per iteration is the discipline that turns a spec into a reliable run. To build the rest of the workflow around it:

Spec-driven development with AI for the full Specify, Plan, Tasks, Implement loop this rule lives inside.
Breaking a PRD into atomic agent tasks for sizing tasks so one fits cleanly in one iteration.
Task lookup tables for agents for ordering and scaling to hundreds of tasks.
Ralph loop failure modes for what goes wrong when this rule and its guardrails are not in place.

Frequently asked questions

What does one task per iteration mean?

It means the agent completes exactly one task per run of the loop, commits the result, and stops. The next iteration starts a fresh agent that picks the next highest-priority incomplete task. The agent never batches several tasks into a single invocation.

Why should an agent not do multiple tasks in one run?

Batching causes three problems. The context window fills with unrelated state and the agent starts contradicting itself, which is context rot. A failure mid-batch leaves several tasks half-finished and unshippable. And the resulting commit bundles many changes, so it is hard to review, revert, or bisect. One task per iteration keeps context small, failures local, and commits atomic.

How does one task per iteration relate to fresh context?

They are two halves of the same design. Each iteration starts the agent with a fresh context window and reconstructs state from files on disk, not from chat history. That only works if the unit of work fits inside one clean window, and one task is the unit sized to do that. Together they keep every iteration crisp: clean slate in, one verified task out.

How does Ralph enforce one task per iteration?

The loop runs the agent once per iteration. Each iteration the agent finds the single highest-priority incomplete task in .agent/tasks.json, works only that task spec, runs tests, lint, and type checks, updates the status, commits, and stops. Because the next iteration starts a brand new agent with fresh context, there is no way to carry work across tasks. The process boundary between iterations is the enforcement.

What if a task is too big to finish in one iteration?

Do not relax the rule, cut the task smaller. A good task is something an agent can finish in one short sitting with its own acceptance criteria. If the agent runs out of room inside one iteration, the breakdown was too coarse. Split the task during the breakdown phase so one task fits cleanly in one iteration.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

Breaking a PRD Into Atomic Agent Tasks

Fri, 17 Apr 2026 00:00:00 GMT

To break a PRD into tasks an agent can build, you decompose it into atomic task packets: small, self-contained units of work, each with one objective, the files to inspect, ordered steps, and acceptance criteria a machine can check. The agent picks one packet, builds it, verifies it, commits, and stops. The PRD is the contract for the whole project. A task packet is the contract for one iteration.

This post is the decomposition itself: what goes inside a single packet, how Ralph stores packets in .agent/tasks.json and .agent/tasks/TASK-{ID}.json, how to size each one so a single iteration can finish and commit, and how dependencies and priority decide the order the loop works them. It assumes you already have a buildable PRD. If you do not, start with how to write a PRD an AI agent can actually build from, then come back here to chop it up.

Why a PRD is the wrong unit of work for an agent

A PRD describes a finished product. An agent does not build finished products. It edits files in a single context window, and that window is finite. Hand it the whole PRD and tell it to build, and one of two things happens. It tries to do everything at once and produces a sprawling diff you cannot review, or it loses the plot halfway through and starts contradicting decisions it made an hour earlier. That second failure is context rot, and it gets worse the longer a single session runs.

The fix is to never ask the agent to hold the whole project in its head. You decompose the PRD into the smallest pieces that still make sense on their own, and you feed the agent exactly one piece per iteration with a fresh context window each time. The Ralph technique is built around this: each loop starts the agent clean, it reads the task list, it picks one packet, and the filesystem carries the memory between passes instead of a long chat history.

So the real question is not “how do I get the agent to build my PRD.” It is “what is the smallest packet of work I can define that the agent can finish and verify in one sitting.” Get that unit right and the loop becomes reliable. Get it wrong and no amount of prompting saves you.

What goes inside an atomic task packet

A task packet is atomic when it has a single objective and everything the agent needs to hit it. Four parts make a packet complete.

The objective. One sentence describing the one thing this packet delivers. Not “build authentication.” That is a feature, not a task. “POST /api/auth/register creates a new user account” is a task. If you cannot state the objective in a single sentence without the word “and,” the packet is too big and you split it.

The files to inspect. Name the files the agent should read before it touches anything, and the files it is expected to change. This is the cheapest way to stop an agent from inventing a parallel module next to the one you already have. In Ralph these live in the step details and in technicalNotes: “extend the existing auth module in src/lib/auth.ts, do not add a second one.” A packet that points the agent at the right files reuses code instead of duplicating it.

The ordered steps. The packet breaks the objective into a short sequence the agent works in order. Each step is concrete enough to act on, and the last step is almost always “write the tests that prove the acceptance criteria.” Tests are steps inside the packet, not a separate task scheduled for later.

Testable acceptance criteria. Each criterion is a condition the agent can confirm by running a command and reading the output. “Login works” is a vibe. “POST with a wrong password returns 401 and the body { error: 'Invalid credentials' }” is a criterion. The test is simple: can a machine return yes or no without your opinion? If not, rewrite it. The discipline of writing verifiable criteria is the same one that makes the PRD buildable, covered in how to write a PRD for an AI agent.

The packet is the unit of verification, not just the unit of work. When the agent finishes, it does not ask you whether it is done. It checks the criteria, and the criteria answer for it.

How Ralph stores this: a lookup table plus per-task specs

Ralph splits the task list into two layers, and the split is what lets a run scale to hundreds of packets without drowning the agent in detail.

The root .agent/tasks.json is a lookup table, not the detail. It is a flat list where each entry is a stub that points at a spec file. The agent scans this list every iteration to find the next thing to do, so it stays lean on purpose.

[
  {
    "id": "TASK-1",
    "title": "Verify project prerequisites and access",
    "category": "setup",
    "specFilePath": ".agent/tasks/TASK-1.json",
    "passes": false
  },
  {
    "id": "TASK-2",
    "title": "Add avatars storage bucket and config",
    "category": "infrastructure",
    "specFilePath": ".agent/tasks/TASK-2.json",
    "passes": false
  },
  {
    "id": "TASK-3",
    "title": "POST /api/avatar uploads and stores a user avatar",
    "category": "api-endpoint",
    "specFilePath": ".agent/tasks/TASK-3.json",
    "passes": false
  }
]

Each stub carries a passes flag. It starts false and only flips to true after the agent verifies the work for that packet. The loop reads this flag to decide what is left. Keeping the table this thin matters: a run with two hundred packets still scans fast, because the table holds titles and pointers, not the full contracts. That scaling pattern is its own topic in task lookup tables for agents.

The detail lives in the per-task spec at .agent/tasks/TASK-{ID}.json. This is the full packet: the objective as a description, the files to inspect inside the steps, the ordered steps, the testable acceptance criteria, the dependencies, an estimated complexity, and any technical notes.

{
  "id": "TASK-3",
  "title": "POST /api/avatar uploads and stores a user avatar",
  "category": "api-endpoint",
  "description": "Accept an image upload from an authenticated user, validate it, store it in the avatars bucket, and save the URL on the user row.",
  "acceptanceCriteria": [
    "POST with a valid PNG or JPEG under 2 MB returns 200 with the stored avatar URL",
    "A file over 2 MB returns 413 with the error text File too large",
    "A non-image content type returns 415",
    "An unauthenticated request returns 401",
    "The avatar URL is persisted on the user row and survives a re-fetch"
  ],
  "steps": [
    {
      "step": 1,
      "description": "Add the upload route handler",
      "details": "Read src/lib/auth.ts for the session helper and src/lib/storage.ts for the bucket client. Add POST /api/avatar, validate size and content type, upload, then update users.avatarUrl.",
      "pass": false
    },
    {
      "step": 2,
      "description": "Write tests for every acceptance criterion",
      "details": "Add Vitest cases for valid upload, oversized file, wrong content type, unauthenticated request, and persistence after re-fetch.",
      "pass": false
    }
  ],
  "dependencies": ["TASK-1", "TASK-2"],
  "estimatedComplexity": "medium",
  "technicalNotes": [
    "Reuse the storage client in src/lib/storage.ts, do not add a second SDK",
    "Strip EXIF data before storing the image"
  ]
}

Notice the four parts of a packet map onto the JSON. description is the objective. The step details name the files to inspect and change. steps is the ordered sequence. acceptanceCriteria is the checkable definition of done. TASK-1 is always reserved for prerequisite verification, so the agent confirms credentials, tools, and access exist before any feature work starts.

Here is how a PRD turns into packets and lands in the lookup table.

flowchart TD
  PRD["prd/PRD.md: goals, constraints, criteria"] --> Decompose["Decompose into atomic packets"]
  Decompose --> P1["tasks/TASK-1.json: prerequisite gate"]
  Decompose --> P2["tasks/TASK-2.json: storage config"]
  Decompose --> P3["tasks/TASK-3.json: upload endpoint"]
  Decompose --> Pn["tasks/TASK-N.json: ..."]
  P1 --> Index["tasks.json lookup table (stubs + passes)"]
  P2 --> Index
  P3 --> Index
  Pn --> Index
  Index --> Loop["ralph.sh: pick one packet per iteration"]
  Loop --> Verify["Build, test, screenshot, commit, set passes true"]

The PRD is the source. Decomposition produces one spec file per packet. The lookup table indexes them. The loop reads the table, opens one spec, and works it. You do not write all of this by hand: the prd-creator skill generates the table and the spec files from your PRD, then you edit the packets that need sharpening.

Sizing a packet so one iteration can finish and commit

The hardest part of decomposition is sizing. Too big and the agent runs out of context before it finishes, leaves the packet half built, and the next iteration starts cold on a mess. Too small and you spend more iterations on overhead than on work. The target is the largest packet that still finishes, verifies, and commits inside a single iteration.

A few concrete rules keep packets in the right range.

One objective, no “and.” If the title needs the word “and” to be honest, it is two packets. “Add the upload endpoint and the avatar UI” is two: the endpoint is an api-endpoint packet, the UI is a ui-ux packet that depends on it. Split on the “and.”

One area of the codebase. A packet that touches the data model, the API, and the frontend in one pass is too wide. Each layer is its own packet. The migration is one. The endpoint that reads the new column is another. The component that renders it is a third. Narrow packets keep the diff readable and the failure isolated.

Verifiable in the steps it contains. If proving the criteria would take more steps than building the feature, the packet is doing too much. A well sized packet has a handful of steps, and the test step covers the criteria without ballooning into a second project.

A clean commit at the end. The end state of every packet is a commit that builds, passes its tests, and changes nothing it did not need to. If you cannot imagine that commit as a single coherent change, the packet is wrong.

The economics back this up. The loop runs one packet per iteration, and you cap iterations with ./ralph.sh -n 50 (the default is 10). A run of small packets makes steady, auditable progress: one commit per packet, one test suite per criterion, one screenshot per UI change. A run of giant packets thrashes, because the agent keeps almost finishing and never quite committing. When you want to watch a single packet land before turning the loop loose, run exactly one iteration:

npx @pageai/ralph-loop
./ralph.sh --once

The rule that one invocation handles exactly one packet, commits, and stops is the reliability backbone of the whole approach. It has enough nuance to deserve its own treatment in one task per iteration.

Dependencies and priority ordering

Atomic packets are not independent of each other. The upload endpoint cannot exist before the storage bucket. The avatar UI cannot render a URL the endpoint does not yet return. Decomposition has to capture this order, or the agent builds on a foundation that is not there and the iteration fails.

Ralph encodes order in two places. The dependencies array on each spec names the packets that must pass first. In the example above, TASK-3 depends on ["TASK-1", "TASK-2"], so the loop will not start the upload endpoint until the prerequisite gate and the storage config both report passes: true. The agent respects this when it selects the next packet, which means you can write the whole task list up front without worrying that the agent jumps ahead.

Priority decides what to do among packets that are all unblocked. Each iteration the loop finds the highest-priority incomplete task whose dependencies are satisfied, opens its spec, and works it. The selection logic each pass is small.

flowchart TD
  Start["Fresh context"] --> Scan["Scan tasks.json for incomplete packets"]
  Scan --> Ready{"Dependencies all passes true?"}
  Ready -->|"no"| Skip["Skip, try next packet"]
  Ready -->|"yes"| Pick["Pick highest priority among ready packets"]
  Skip --> Scan
  Pick --> Work["Open TASK-{ID}.json, work the steps"]
  Work --> Gate["Tests, lint, types, screenshot"]
  Gate -->|"fail"| Work
  Gate -->|"pass"| Commit["Set passes true, commit, stop"]

Two practices keep ordering dependable. First, front-load the foundation. The prerequisite gate is TASK-1 for a reason: nothing should run before the agent confirms it has the access and tools to run at all. Data-model packets come early, because most feature packets depend on them. Second, keep dependency chains shallow. A packet that depends on a packet that depends on a packet is a sign the work is really one larger unit you split too aggressively, or that an intermediate packet is doing too little. Wide and shallow beats narrow and deep, because shallow graphs give the loop more ready packets to choose from at any moment, which keeps it moving even if one branch is blocked.

When you need to reorder mid-run, you do not kill the loop. You edit .agent/STEERING.md, and the agent handles that critical work on its next iteration before returning to the task list. That is how you inject “fix the failing migration before anything else” without losing momentum.

A short worked example

Take “let users upload a profile avatar” from a PRD and watch it become packets.

That sentence is a feature, not a task. Decomposition asks: what are the smallest verifiable units, and in what order. TASK-1 is the prerequisite gate, always. TASK-2 configures the storage bucket and is a dependency for everything that stores a file. TASK-3 is the upload endpoint, depending on the bucket. TASK-4 is the avatar component in the UI, depending on the endpoint because it renders the URL the endpoint returns. TASK-5 handles deletion, depending on the upload existing.

Each packet gets criteria a machine can check, not opinions. For the endpoint: a valid image under the size limit returns 200 with a URL, an oversized file returns 413, a wrong content type returns 415, an unauthenticated request returns 401. For the UI: the component shows a placeholder when no avatar is set, shows the image after a successful upload, and a Playwright run plus a screenshot confirms it. The feature that read as one line in the PRD is now five committed, tested steps, each small enough to finish in a single iteration, ordered so the loop never builds ahead of its foundation.

The framing of phases that produces these packets (specify, plan, decompose into tasks, implement and verify) comes from GitHub Spec Kit, and the loop that runs the packets autonomously was popularized by Geoffrey Huntley in his original Ralph writeup. Decomposition is the phase that decides whether the loop succeeds, which is why it is worth slowing down for.

Where to go next

If you are building this workflow, read across the spec-driven cluster:

Spec-driven development with AI for the full Specify, Plan, Tasks, Implement workflow these packets sit inside.
How to write a PRD an AI agent can actually build from for the goals, constraints, and acceptance criteria you decompose here.
One task per iteration for the rule that makes one-packet-at-a-time reliable.
Task lookup tables for agents for scaling the table to hundreds of packets.

For the mechanics of the loop that reads these packets on every pass and the fresh-context design behind it, start with what is the Ralph technique.

Frequently asked questions

How do I break a PRD into tasks an AI agent can build?

Decompose the PRD into atomic task packets, where each packet has one objective, the files to inspect, ordered steps, and acceptance criteria a machine can check by running a command and reading the output. Split on any objective that needs the word and, keep each packet inside one area of the codebase, and make sure the agent can finish and commit it in a single iteration.

What makes a task packet atomic?

A packet is atomic when it has a single objective and everything the agent needs to hit it without holding the rest of the project in its head. That means one deliverable, the files to read and change, a short ordered sequence of steps with tests as the final step, and verifiable acceptance criteria. If you cannot state the objective in one sentence without the word and, the packet is too big.

How does Ralph store a decomposed PRD?

Ralph uses two layers. The root .agent/tasks.json is a lean lookup table of stubs, each with an id, title, category, a pointer to a spec file, and a passes flag. The detail lives in per-task specs at .agent/tasks/TASK-{ID}.json, which hold the description, acceptance criteria, ordered steps, dependencies, estimated complexity, and technical notes. The agent scans the table to pick a packet and opens the spec to work it.

How big should a single agent task be?

The right size is the largest packet that still finishes, verifies, and commits inside one iteration. Too big and the agent runs out of context and leaves the work half done. Too small and overhead dominates. Aim for one objective, one area of the codebase, a handful of steps including the tests, and a single clean commit at the end.

How do dependencies and priority decide task order?

Each spec has a dependencies array naming the packets that must pass first, so the loop will not start a packet until its dependencies report passes true. Among packets whose dependencies are satisfied, the loop works the highest priority one. Front-load the prerequisite gate and data-model packets, keep dependency chains shallow, and edit STEERING.md to reorder mid-run without stopping the loop.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

How to Steer a Running AI Agent Without Stopping the Loop

Mon, 13 Apr 2026 00:00:00 GMT

To steer a running AI agent, edit .agent/STEERING.md while the loop is going. The agent reads that file at the top of every iteration, before it picks a task. Anything you write there gets handled first, in order, then the agent removes the finished items and goes back to the task list. You change direction without killing the process and without losing the momentum of a warm run.

This is the redirect control inside the larger system for running an AI coding agent overnight. A loop that runs for hours will sometimes pick a task you no longer want, chase a dead end, or need a hotfix you only just noticed. Steering ai agent behavior through a file is how you correct course mid-flight instead of stopping, editing, and starting over.

What steering an AI agent actually means

Steering is not a chat message and not a new prompt. It is a single Markdown file, .agent/STEERING.md, that lives next to the rest of the agent state. The Ralph prompt has one job for it. In the “Before Starting” section of .agent/PROMPT.md, the agent is told to check .agent/STEERING.md for critical work, complete the items in sequence, remove them when done, and only proceed to implement tasks if no critical work is pending.

That ordering is the whole mechanism. Because each iteration starts the agent with a fresh context window, the agent rereads the prompt and the steering file every single loop. There is no stale chat history to fight and no need to interrupt the agent mid-thought. You write to a file, and the next clean iteration discovers it.

A steering file looks like a short work order. The default one in the repo handles sandbox setup before any feature work runs:

# Critical Steering Work

## Install and verify dependencies

Run `npm install --ignore-scripts`, then fix native arm64 binaries.

## Main Tasks

Install Playwright system deps, start the dev server, take a screenshot.

---

After you finish this work, exit with message `Steering complete`.

You can replace that content with whatever you need the agent to do next. The file is plain text, so you edit it with any tool from any machine that has the working tree, including a shell inside the sandbox.

When to steer a running agent

Steer when the loop is healthy enough to keep running but pointed at the wrong thing, or when something urgent jumps the queue. There are three common triggers.

The agent is stuck. You are watching the run and the same failure keeps coming back across iterations. Maybe a test depends on a binary that did not install, or a dev server never came up. The agent is not blocked enough to emit a promise tag, but it is spinning. A steering note that tells it exactly how to fix the environment clears the jam. Spotting this early is the payoff of observability for autonomous coding agents: you see the climbing iteration time and the repeated debugging step before the loop burns ten more iterations.

The agent went the wrong direction. The task list was fine when you wrote it, but the agent picked a task whose approach you now disagree with, or requirements changed since you started the run. You do not want to throw away the work it already shipped. You want it to switch tracks on the next iteration.

You have an urgent fix. A bug landed in production, a dependency needs pinning, or a teammate needs a small change merged into the same branch. The loop is the fastest path to get it done, and you would rather inject the work than wait for the run to finish.

Steering is the wrong tool for two cases. If the agent is fundamentally confused about the goal, fix .agent/tasks.json or the PRD instead, because steering is for one-off interventions, not for rewriting the plan. And if the agent emitted BLOCKED or DECIDE and the loop already exited, you do not steer a stopped process. You answer it and rerun, which I cover below.

How the loop reads STEERING.md every iteration

The reason steering works without a restart is that the loop already reopens the file on every pass. Each iteration is a clean run of the agent against the prompt, and the prompt routes through the steering check before it ever touches the task list.

flowchart TD
    Start["Iteration starts (fresh context)"] --> Read["Read .agent/PROMPT.md"]
    Read --> Check{"STEERING.md has critical work?"}
    Check -->|"yes"| Steer["Do steering items in sequence"]
    Steer --> Remove["Remove finished items from STEERING.md"]
    Remove --> Tasks["Pick highest-priority task in tasks.json"]
    Check -->|"no"| Tasks
    Tasks --> Verify["Run tests, lint, typecheck"]
    Verify --> Commit["Commit, emit promise tag"]
    Commit --> Next["Next iteration"]
    You["You edit STEERING.md mid-run"] -.->|"injected here"| Check

The dotted edge is the part you control. Your edit lands in the file at any moment, and the next iteration picks it up at the diamond. You never have to time it perfectly. If iteration 12 is in flight when you save the file, iteration 13 reads your note. Because the agent removes completed steering items, the file empties itself out and the loop returns to normal task work without you touching it again.

This is why a fresh context per iteration is a feature, not a limitation. A single long session would have buried your note under thousands of tokens of prior reasoning. A loop that reloads its instructions every pass treats the file as the source of truth, so the latest version of .agent/STEERING.md always wins.

Steering versus killing and restarting the loop

The blunt alternative is to stop the run, edit something, and start again. Steering beats that on three counts.

You keep warm state. A sandbox that already installed dependencies, built the project, and warmed its caches is expensive to recreate. Ralph runs each agent in a deterministic Docker Sandbox named ralph-<agent>-<dir>-<hash8>, and that sandbox persists between iterations. Killing the loop and recreating the box means paying the setup cost again. Steering reuses the running sandbox.

You keep the run history intact. Every iteration writes a clean transcript to .agent/history/, appends to .agent/logs/LOG.md, and commits per task. A restart starts a new session id and fragments that trail. Steering threads your intervention into the same continuous record, so the morning review reads as one story.

You avoid the gap. When you kill a loop manually, you have to remember to restart it. People walk away and forget. A steering note keeps the loop alive and self-correcting, which is the entire point of an unattended overnight run.

There is one case where stopping is correct: when you want to change how the loop runs, not what it does next. Flags like the iteration count and the agent are set at launch, so switching from ./ralph.sh -n 50 to a different agent with ./ralph.sh --agent codex does require a restart. For everything that is “do this work next,” steer instead.

If you only need to validate a single steering note before trusting it overnight, run one pass with ./ralph.sh --once, confirm the agent did what the file said, then start the full loop.

How to write a steering note that works

A good steering note reads like a task spec: specific, ordered, and verifiable. A bad one reads like a vibe. The agent reads your note with a fresh context, so it has no memory of the hallway conversation in your head. Spell it out.

Write the exact commands and file paths. “Fix the build” is vague. The agent has to guess what broke and what done looks like. Compare:

# Critical Steering Work

## Pin the failing dependency

1. In `package.json`, set `vite` to `5.4.10` exactly.
2. Run `npm install --ignore-scripts`.
3. Run `npm run build` and confirm it exits 0.
4. Commit with message `fix: pin vite to 5.4.10`.

---

After you finish this work, exit with message `Steering complete`.

Every line is checkable. The agent knows the version, the commands, the success condition (build exits 0), and the commit message. That is the same standard the loop expects from a real task, and the same reason verification loops matter: a steering note with a verifiable end state lets the agent prove it is done instead of guessing.

Give the agent an exit condition. The default file ends with “After you finish this work, exit with message Steering complete.” That tells the agent the boundary of the steering work so it does not bleed into task work uninvited. Keep that pattern. Without a clear end, the agent may either stop too early or wander.

Keep it small. Steering is for one or a few critical items, not a second task list. If your note grows into a dozen steps across unrelated areas, that is a sign the work belongs in .agent/tasks.json as real tasks with their own specs. Steering is the fast lane, not the highway.

Order matters. The prompt says complete items in sequence. List prerequisites first. If the agent must install a binary before a test can pass, the install goes above the test.

A few quick contrasts:

Vague: “Make the homepage better.” Specific: “On the homepage hero, change the CTA label to Start free, verify with a Playwright screenshot saved to .agent/screenshots/.”
Vague: “Tests are flaky, look into it.” Specific: “The test auth.spec.ts fails on a timeout. Increase the wait in that file to 10 seconds and rerun it until green.”
Vague: “Clean up the deps.” Specific: “Remove lodash from package.json, replace its three usages in src/utils/ with native equivalents, run the unit tests.”

The pattern is always the same. Name the file, name the command, name the proof.

Combining steering with BLOCKED and DECIDE promises

Steering and promise tags solve different halves of the human-in-the-loop problem, and they work together.

Promise tags are how the agent talks to you. When the agent cannot continue, it emits <promise>BLOCKED:reason</promise> and the loop exits with code 2. When it needs a decision it cannot make alone, it emits <promise>DECIDE:question</promise> and exits with code 3. A clean finish is <promise>COMPLETE</promise> with exit code 0, and hitting the iteration cap is exit code 1. Ralph plays a sound and sends a desktop notification on BLOCKED and DECIDE, so you find out the moment a human is actually needed.

Steering is how you talk back. The promise tells you the loop stopped and why. Your answer goes into .agent/STEERING.md, and then you rerun the loop. The next iteration reads your steering note first, handles the unblock or the chosen direction, removes it, and continues with the task list. The flow is tight:

# loop exits 2 with BLOCKED:cannot reach npm registry
# you allow the domain from the host, then leave a steering note
# in .agent/STEERING.md describing the retry, then:
./ralph.sh -n 50

For a DECIDE, the agent gave you a question like “Option A vs B.” You pick one in the steering file in plain terms: “Use option A. Implement the REST client, not the GraphQL one. Then continue tasks.” The agent does not relitigate the choice because the steering note is now the instruction, and the fresh context means it reads that note as current truth.

This pairing is the reason an overnight run stays autonomous without being unaccountable. The agent stops itself on the two events that genuinely need a person, notifies you, and waits. You drop a precise note into one file and restart. The promise mechanics behind those exit codes are worth knowing in full if you want the loop to stop on a signal rather than a guess, and the deny-by-default network policy that triggers many BLOCKED exits is enforced by the sandbox, not the agent.

When a steering note itself is not enough, get inside the box. List the running sandboxes and open a shell to debug by hand, then write what you learned back into the steering file:

sbx ls
sbx exec -it <ralph-sandbox-name> bash

Print the exact name for your project with ./ralph.sh --print-name. Between promise tags that pull you in, a steering file that pushes instructions back, and a sandbox you can open and inspect, you can run a long autonomous loop and still keep both hands on the wheel whenever you want them there.

Frequently asked questions

How do I steer a running AI agent in a Ralph loop?

Edit the .agent/STEERING.md file while the loop is running. The agent reads that file at the top of every iteration, before it picks a task from tasks.json. It completes the steering items in sequence, removes them when done, and then resumes normal task work. Because each iteration starts with a fresh context, you do not have to time the edit precisely. The next iteration picks up whatever the file says.

Do I have to stop the loop to change what the agent is doing?

No. That is the point of steering. Editing STEERING.md injects work into the next iteration without killing the process, so you keep the warm sandbox, the running session, and the per-task git history intact. You only need to restart the loop when you want to change how it runs, such as switching the agent or the iteration count, since those flags are set at launch.

What makes a good steering note?

Specific, ordered, verifiable instructions. Name the exact files and commands, list prerequisites first, and give a clear success condition such as a build exiting 0 or a test going green. End the note with an explicit exit message so the agent knows where steering work stops. Keep it to one or a few critical items. If it grows into a full plan, that work belongs in tasks.json as real tasks instead.

How does steering work together with BLOCKED and DECIDE promises?

Promise tags are how the agent signals it needs you. BLOCKED exits with code 2 and DECIDE exits with code 3, both with a desktop notification. Steering is how you respond. You write the unblock steps or the chosen option into STEERING.md and rerun the loop, and the next fresh-context iteration reads your note first, handles it, removes it, and continues the task list.

Where does the agent look for steering instructions?

In .agent/STEERING.md. The .agent/PROMPT.md file tells the agent in its Before Starting section to check that file for critical work, complete items in sequence, remove them when done, and only proceed to implement tasks if no critical work is pending. So the latest version of STEERING.md is always the source of truth for what the agent does next.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

Claude Code vs Codex vs Cursor vs Gemini: Best CLI for Long-Running Agent Loops

Wed, 08 Apr 2026 00:00:00 GMT

There is no single best agentic CLI for long-running loops. The honest answer is that you pick per task, and the agent matters less than the loop you wrap around it. Claude Code, OpenAI’s Codex CLI, the Cursor CLI agent, Gemini CLI, GitHub Copilot CLI, and opencode all run inside Ralph behind the same --agent flag, so swapping one for another is a one word change, not a rewrite. This post compares the six on the dimensions that actually decide a multi-hour run: autonomy quality, cost, model options, tool use, and ecosystem.

I am not going to quote benchmark numbers. Vendor leaderboards move every few weeks and rarely reflect how an agent behaves over dozens of iterations against your codebase. What follows is concrete and opinionated, grounded in how each CLI is invoked and how each one tends to behave when you leave it running.

Why “best” is the wrong question for a multi-hour loop

A one-shot demo and a multi-hour loop are different sports. In a demo, raw reasoning on the first try wins. In a loop, the agent runs the same task family dozens or hundreds of times, sees its own test failures, and fixes them on the next pass. What you actually want is an agent that responds well to feedback, follows a structured prompt, and exits cleanly so the harness can decide whether to loop again.

That reframes the comparison. The strongest model on a leaderboard can still lose a long run if it ignores the prompt structure, never stops on its own, or burns your budget on token-heavy reasoning for mechanical work. A merely good model with tight verification gates will grind toward correct. This is the core point from the field guide to agentic coding CLIs: the harness around the agent carries more of the result than the agent does.

So the real question is not “which CLI is smartest.” It is “which CLI holds up when I leave it alone.” Hold that distinction while you read the comparison.

How Ralph makes the six CLIs interchangeable

Ralph is a Bash script you point at a project. It does not reimplement any agent. It wraps whichever one you pick, runs it inside an isolated Docker Sandbox, watches the output, and loops with a fresh context each iteration. Three design choices are what make the agent swappable.

First, one flag selects the agent. claude is the default, and you switch with --agent (short -a):

# Claude Code (default), 50 iterations
./ralph.sh -n 50

# Swap the agent, nothing else changes
./ralph.sh --agent codex
./ralph.sh -a cursor -n 5

Second, a bare -- separator forwards anything after it straight to the underlying CLI. Ralph parses its own flags first, then hands the rest to the agent untouched. That is how you pin a model without Ralph needing to know each vendor’s model names:

./ralph.sh --agent codex -- --model gpt-5.5
./ralph.sh -a gemini -- --model pro

Third, each agent gets its own deterministic sandbox, named ralph-<agent>-<current-dir>-<hash8>. Your Claude sandbox and your Codex sandbox never share credentials, history, or installed tools, so you can compare agents on the same project without them stepping on each other. Print the name without starting a run:

./ralph.sh --print-name --agent codex

Under the hood, Ralph builds a different invocation per agent but keeps the loop identical. The expansions are:

# claude:    sbx run ... claude .   -- --output-format stream-json --verbose -p "$PROMPT_CONTENT"
# codex:     sbx run ... codex .    -- exec "$PROMPT_CONTENT"
# copilot:   sbx run ... copilot .  -- -p "$PROMPT_CONTENT"
# cursor:    sbx run ... cursor .   -- -p "$PROMPT_CONTENT"
# gemini:    sbx run ... gemini .   -- -p "$PROMPT_CONTENT"
# opencode:  sbx run ... opencode . -- run "$PROMPT_CONTENT"

Every one of those runs the same loop: pick the top task from .agent/tasks.json, work it, run the verification stack, commit, and either continue or stop on a promise tag. Because the loop is shared, you can treat the choice of CLI as a variable. Pick one, run it, and if it stalls on your codebase, change the flag and try another. The mechanics never move.

The dimensions that decide a long run

Five things separate these agents once you are running them unattended. I will go through each, then break the agents down one by one.

Autonomy quality is how well the agent works without a human in the chair. Does it follow the prompt structure, stay on one task per invocation, run its own tests, and emit a clean completion signal? A loop has nobody to answer “should I proceed?”, so any agent that pauses for approval will stall unless you put it in a non-interactive mode.

Cost over a loop is dominated by model choice and iteration count, not the per-call price you see in a demo. Fifty iterations on a flagship model add up. The lever is the model flag and the iteration cap, which I cover in depth alongside the overnight-run architecture in how to run an AI coding agent overnight.

Model options decide whether you can match the model to the task. Heavy reasoning (architecture, gnarly refactors) rewards the strongest model. Mechanical work (CRUD wiring, lint fixes, filling in tests) runs fine and cheaper on a mid tier model. The more model choices a CLI exposes through -- --model, the more you can tune.

Tool use is how the agent edits files, runs shell commands, and reads results. All six edit files and run commands. The difference shows up in how cleanly they run headless and how readable their output is while looping.

Ecosystem is auth, billing, and which world you already live in. A team standardized on GitHub auth has a different default than one paying for an Anthropic or OpenAI plan.

Claude Code

Claude Code is Ralph’s default for a reason. It is steady on long, multi-step tasks and follows a structured prompt closely, which is exactly what a fresh-context loop needs. Ralph runs it with --output-format stream-json --verbose, and that structured stream gives the loop the richest live, readable step view of any of the six. When you want to watch what the agent is doing each iteration, Claude Code shows the most.

It runs in bypass-permissions mode inside the sandbox (--dangerously-skip-permissions, or --permission-mode bypassPermissions), so it never pauses for approval during an unattended run. Model selection goes through -- --model. For autonomy quality and clarity of feedback, this is the smoothest first run. The end-to-end setup is in running Claude Code in a loop. See the Claude Code docs for the flag surface.

Codex CLI

Codex is OpenAI’s agent, run through its non-interactive exec mode. It is a strong reasoner on hard, self-contained problems, which makes it a natural pick when the task is logic-heavy rather than sprawling. Pin a model with -- --model gpt-5.5.

The thing to know about Codex in a loop: codex exec runs read-only by default, so a loop using the default mode will spin without ever editing a file. You grant write access deliberately with -- --sandbox workspace-write --ask-for-approval never, or bypass Codex’s own gates entirely with -- --dangerously-bypass-approvals-and-sandbox. The bypass flag is safe here because the microVM is the real boundary, not Codex policing itself. Codex also has a clean --json event stream for CI parsing. The full wiring, including the read-only gotcha and CI flags, is in running the Codex CLI in an autonomous loop.

Cursor CLI agent

The Cursor CLI agent brings the headless cursor-agent to the loop, invoked with -p. If your team already lives in Cursor, running the same agent unattended over a sandbox lets you review a finished diff in the morning instead of pair-programming all afternoon. The autonomy quality is solid, and the appeal is continuity: you keep the agent and the mental model you already trust, and you add looping on top. Model and other flags pass through after -- like every other agent.

Gemini CLI

Gemini CLI is Google’s agent, driven with -p and model selection through -- --model pro. It is worth reaching for when you want a different model family in the mix or you already live in the Google ecosystem. The argument for keeping a non-Anthropic, non-OpenAI option in your rotation is practical: when one agent stalls on a specific task, a different model family sometimes walks straight through it. Ralph makes that switch a one word change.

GitHub Copilot CLI

Copilot CLI slots in for teams standardized on GitHub’s tooling and auth. Ralph runs it with the same -p prompt pattern and the same sandbox boundary as the rest. The pull here is ecosystem, not raw capability: if your auth, your billing, and your repos already run through GitHub, Copilot is the path of least friction. The loop treats it identically to the others.

opencode

opencode is the open source option, invoked with its run subcommand. It is the pick when you want to avoid vendor lock-in, run an agent you can fully inspect and modify, or route to a provider and model of your own choosing. For cost-sensitive runs where you want maximum control over the model layer, an open agent you can point at any backend is a real advantage. You trade some of the polished, batteries-included feel of the vendor CLIs for control and inspectability.

Pick this when

Here is the practical version, stripped of hedging. Match the agent to the situation rather than hunting for one winner.

Pick Claude Code when you want the smoothest first loop and the clearest live view of what the agent is doing. It is the right default, and the right place to start if you are new to running loops.
Pick Codex when the task is logic-heavy and self-contained, and you want explicit model pinning plus a clean JSON event stream for CI. Remember to grant write access, or it will not edit anything.
Pick Cursor when your team already uses Cursor and you want the same agent to run unattended so you review a diff instead of babysitting.
Pick Gemini when you want a different model family in your rotation, or you are already in the Google ecosystem.
Pick Copilot when your auth and billing already run through GitHub and you want the least new setup.
Pick opencode when you want an open, inspectable agent, no vendor lock-in, or full control over the model and provider behind it.

A decision guide for the common case:

flowchart TD
  Start(["Choosing an agent for a long loop"]) --> Q1{"New to running loops?"}
  Q1 -->|"yes"| Claude["Start with claude (default, richest live view)"]
  Q1 -->|"no"| Q2{"What matters most?"}
  Q2 -->|"hard reasoning task"| Codex["codex (grant write access)"]
  Q2 -->|"already in Cursor"| Cursor["cursor"]
  Q2 -->|"different model family"| Gemini["gemini -- --model pro"]
  Q2 -->|"GitHub-standardized team"| Copilot["copilot"]
  Q2 -->|"open, no lock-in"| Opencode["opencode"]
  Claude --> Swap{"Stalls on your codebase?"}
  Codex --> Swap
  Cursor --> Swap
  Gemini --> Swap
  Copilot --> Swap
  Opencode --> Swap
  Swap -->|"yes"| Change["Change one --agent flag, retry"]
  Swap -->|"no"| Ship["Let the loop run, review in the morning"]

The last edge is the important one. Because the harness is shared, “this agent stalled” is not a dead end. It is a flag change. That is the whole reason Ralph treats the agent as swappable rather than picking one for you.

What actually moves the result

If you take one thing from this comparison, take this: a weaker agent inside a good loop will out-ship a stronger agent you babysit in a single session. The loop gives the agent fresh context every iteration, keeps state on disk, isolates it in a sandbox, and runs real verification gates. Those four things matter more than the gap between any two of these CLIs.

Fresh context per iteration is what beats context rot. Each pass boots the agent clean, so it does not drag an hours-long transcript from one task to the next. The filesystem and git history are the memory layer: progress lives in .agent/tasks.json, the per-task spec files, .agent/logs/LOG.md, and the git log, not in a chat window. This is the mechanic Geoffrey Huntley described in the original Ralph writeup, and it applies identically to all six agents.

Verification is what lets a cheaper model succeed. The loop assumes a stack of Playwright for end-to-end tests, Vitest for unit tests, TypeScript for types, ESLint for lint, and Prettier for format. The repo mantra is blunt: if you didn’t test it, it doesn’t work. The agent does not need to be right on the first try. It needs to write code, run the gates, read the failures, and fix them next pass. When you compare agents for long runs, you are really comparing how each one responds to that feedback, not how clever its first draft looks.

The sandbox is what makes any of this safe to walk away from. Ralph runs every agent inside a Docker Sandbox microVM with deny-by-default networking, so bypass-permissions mode is reasonable: the worst the agent can do is wreck a disposable VM, not read your SSH keys. You open exactly what a task needs with sbx policy allow network <name> <domain>. The full reasoning is in the Docker Sandboxes docs.

And the loop stops on a signal, not a vibe. Each agent emits a promise tag that Ralph reads:

<promise>COMPLETE</promise> means every task is finished.
<promise>BLOCKED:reason</promise> means the agent needs human help.
<promise>DECIDE:question</promise> means it needs a decision you have to make.

Those map to exit codes: 0 for COMPLETE, 1 for MAX_ITERATIONS, 2 for BLOCKED, and 3 for DECIDE. You branch on them in CI or a wrapper script, which means the comparison between agents is also fair: every one of them ends with a verdict you can act on.

Putting it together

There is no best agentic CLI, so stop looking for one. Start with Claude Code because it is the steady default with the clearest output. Reach for Codex on hard reasoning tasks, Cursor when your team already uses it, Gemini for a different model family, Copilot when you are GitHub-standardized, and opencode when you want an open agent with no lock-in. Then let the harness do the heavy lifting.

The shortest path to running any of them is three commands:

# 1. install
npx @pageai/ralph-loop

# 2. authenticate the agent inside its sandbox
./ralph.sh --login --agent codex

# 3. run the loop on your chosen agent and model
./ralph.sh --agent codex -n 50 -- --model gpt-5.5

Swap codex for any of the six and the loop is identical. Pick the agent, pin the model, and let it work one task per iteration inside the sandbox while you sleep. If it stalls, you already know the fix: change one flag.

Frequently asked questions

Which is the best agentic CLI for long-running loops?

There is no single winner. Claude Code is the steady default with the richest live output, Codex is strong on hard reasoning tasks, Cursor suits teams already using Cursor, Gemini brings a different model family, Copilot fits GitHub-standardized teams, and opencode is the open source option. The loop you wrap around the agent matters more than the agent, so pick one and swap with the --agent flag if it stalls.

Claude Code vs Codex: which should I use?

Use Claude Code as the default when you want the smoothest unattended run and the clearest live view of each iteration, since Ralph parses its stream-json output. Use Codex for logic-heavy, self-contained problems and CI pipelines that parse its JSON event stream. One gotcha: codex exec is read-only by default, so grant write access with -- --sandbox workspace-write --ask-for-approval never or it will not edit files.

How do I switch between agents in Ralph?

Pass the --agent flag, or -a for short. ./ralph.sh runs Claude Code by default, ./ralph.sh --agent codex runs Codex, and ./ralph.sh -a cursor -n 5 runs Cursor for five iterations. Each agent gets its own sandbox named ralph-<agent>-<dir>-<hash8>, so they do not share credentials or history. The loop itself is identical across all six.

Does the choice of agent matter more than the loop?

No. A weaker agent inside a good loop, with fresh context each iteration, state on disk, sandbox isolation, and real verification gates, will out-ship a stronger agent you babysit in a single session. Those four properties decide the result more than the gap between any two CLIs, which is why Ralph treats the agent as a swappable variable.

How do I pick a model for each agent?

Model selection is an agent flag, not a Ralph setting, so you pass it after the -- separator. For example ./ralph.sh --agent codex -- --model gpt-5.5 or ./ralph.sh -a gemini -- --model pro. Match the model to the task: a strong model for heavy reasoning, a cheaper mid tier model for mechanical work, since model choice and iteration count are the biggest cost levers in a long run.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

Ralph Loop Failure Modes (Context Rot, Runaway Cost) and How to Avoid Them

Sat, 04 Apr 2026 00:00:00 GMT

A Ralph loop does not fail in mysterious ways. It fails in a short list of predictable ones: the agent forgets the plot, the loop burns money forever, it thrashes on a task that is too big or too vague, it ships work that looks done but is wrong, or it damages something on your machine. Each of these has a known cause and a specific guardrail. None of them require luck to avoid.

This post walks through every failure mode of running an AI coding agent in a loop, why each one happens, and the exact mechanism in ralph.sh that prevents it. If you are setting up a loop for the first time or wondering why a run went sideways, this is the checklist.

What are the failure modes of a Ralph loop?

Five, mostly. They are context rot, runaway cost, thrashing on a bad task, silent wrong work, and sandbox damage. Every one maps to a guardrail you can turn on or design around. Here is the short version before the details:

Context rot. Fixed by fresh context per iteration and state on disk.
Runaway cost and infinite loops. Fixed by an iteration cap, a completion promise, and a budget you set.
Thrashing on a bad or oversized task. Fixed by atomic tasks, one task per iteration, and the BLOCKED and DECIDE promise tags.
Silent wrong work. Fixed by verification gates and screenshots.
Sandbox escape or damage. Fixed by running the agent inside a Docker Sandbox.

The rest of this post takes each one in turn.

Context rot: the agent loses the plot

Context rot is the slow decay of an agent’s reasoning as its context window fills with stale and conflicting information. Old tool output, abandoned plans, your corrections, the agent’s own apologies, half-finished edits: all of it competes with the task that actually matters right now. The longer a single session runs, the worse the signal-to-noise ratio gets. You see it as repeated mistakes, forgotten constraints, and confident edits that quietly undo earlier good work.

This is the failure the Ralph technique was built to kill, so the guardrail is the core of the design rather than a bolt-on.

Fix: fresh context every iteration

Each iteration spawns the agent with a clean context window. It reads only what matters right now: the prompt, a short project summary, the task list, and the spec for the one task it is about to work. There is no transcript of the previous twelve iterations clogging the window. The model spends its attention on the current task instead of re-reading its own history.

Think of it as a series of sprints rather than one marathon. A marathon session accumulates fatigue. A fresh sprint each time stays sharp.

Fix: state lives on disk, not in chat

If the agent forgets everything between iterations, how does it make progress? Because progress does not live in the conversation. It lives in files. Ralph keeps state under .agent/:

.agent/
├── PROMPT.md      # Prompt sent to the agent each iteration
├── tasks.json     # Task lookup table
├── tasks/         # Per-task specs (TASK-{ID}.json)
├── logs/LOG.md    # Progress log
└── history/       # Per-iteration output logs

When a fresh agent boots, it reads .agent/tasks.json to see what is done, reads .agent/logs/LOG.md to see what happened recently, and reads the git log to see the actual committed changes. The code on disk is the record. The window never grows large enough to rot because it resets every pass. The deeper version of this design, including how the prompt file makes a fresh agent reorient in seconds, is in how to write the PROMPT.md file that drives a Ralph loop.

Runaway cost and infinite loops: the money fire

The naive Ralph loop is one line:

while :; do cat PROMPT.md | your-agent-cli; done

That loop never stops on its own. It has no iteration cap and no notion of success. Point it at a paid model and walk away, and it will happily keep calling the API until your bill says otherwise. Even when the work is genuinely done, a loop without a stop condition will keep re-running the agent to rediscover that there is nothing left to do, paying full freight each time.

Runaway cost has two shapes. One is the loop that never terminates. The other is the loop that terminates eventually but does far more iterations than the work needed. Both are guardrail problems, not model problems.

Fix: an iteration cap with -n

ralph.sh takes a hard cap on iterations. The default is ten. You set a higher one explicitly:

./ralph.sh -n 50
./ralph.sh --max-iterations 5

To smoke test the setup without committing to a long run, do exactly one pass:

./ralph.sh --once

When the loop hits the cap with work still pending, it exits with code 1 (MAX_ITERATIONS). That is not a crash. It is the safety net doing its job. You read the log, decide whether to top up the budget, and run it again.

Fix: a completion promise, not a vibe

The loop stops on an explicit signal, never on a guess. The agent emits a promise tag to declare where things stand:

<promise>COMPLETE</promise> every task is finished.
<promise>BLOCKED:reason</promise> the agent needs a human to clear something.
<promise>DECIDE:question</promise> the agent hit a real decision point.

ralph.sh watches for these tags and translates them into exit codes:

Code	Meaning
0	COMPLETE. All tasks finished.
1	MAX_ITERATIONS. Reached the cap.
2	BLOCKED. Needs human help.
3	DECIDE. Needs a human decision.

A COMPLETE ends the run cleanly the moment the work is actually done, so you do not pay for victory laps. The full design of the stop condition, and why a promise beats letting the agent decide it feels finished, is in completion promises and exit codes.

Fix: a budget you choose up front

Cost control is mostly about deciding limits before you start: how many iterations, which model, and what the loop is allowed to touch. A cheaper model on a well specified task can outperform an expensive model on a vague one, because the expensive model spends its budget flailing. The full treatment of caps, model choice, and the verification gates that keep a loop from spinning is in cost control for autonomous AI coding agents.

Thrashing on a bad or oversized task

Give an agent a task like “refactor the billing system” and it will thrash. The task is too big to hold in one iteration and too vague to verify, so the agent makes a sprawling change, second-guesses it, partially reverts, and produces a commit you cannot review. Repeat that across iterations and the loop spins without converging. This is the most common reason a loop “does not work,” and it is almost always a task design problem rather than an agent problem.

Fix: atomic tasks

The unit of work matters. A task should be small enough to finish in a single iteration and specific enough to verify. “Add a unit test for the discount calculation in cart.ts” is atomic. “Improve test coverage” is not. The loop is only as good as the tasks you feed it. Garbage tasks in, garbage commits out. How to decompose a large project into atomic, independently verifiable packets is the heart of spec-driven development, and it is upstream of everything the loop does.

Fix: one task per iteration

The rule that keeps a loop reliable is blunt: the agent completes exactly one task, commits, and stops. It never batches several tasks into one iteration. Batching is how an agent drifts off scope and produces a tangled diff. One task per invocation keeps each commit reviewable and each iteration’s blast radius small.

This pairs with the task lookup table. The agent reads .agent/tasks.json, picks the highest-priority incomplete task, opens its spec at .agent/tasks/TASK-{ID}.json, works only those steps, and exits. The table is a lightweight index, so a project can hold hundreds of tasks while each iteration loads only the one it needs.

Fix: BLOCKED and DECIDE instead of guessing

When a task is genuinely underspecified or the agent hits a wall it cannot clear, the worst outcome is for it to guess and burn iterations on a wrong assumption. The promise tags give it an honest exit. BLOCKED:reason stops the loop and hands you the blocker. DECIDE:question stops and asks for your call. The loop returns exit code 2 or 3, and you are not staring at a dead terminal wondering what happened. A loop that stops to ask is far cheaper than a loop that thrashes in silence.

Silent wrong work: it looks done but it is broken

The scariest failure is the one that looks like success. The agent flips a task to done, commits, and moves on, but the code does not actually work. Maybe it compiles and the tests it wrote test the wrong thing. Maybe the UI renders but the button does nothing. Across an overnight run, silent wrong work compounds: later tasks build on the broken one, and you wake up to a green task list and a red product.

The cause is letting the agent self-assess on a vibe. The fix is to take that judgment away from the agent and give it to a tool that cannot be fooled by optimism.

Fix: verification gates

Before the agent calls a task done, it runs the project’s checks. Ralph assumes a verification stack: Playwright for end to end tests, Vitest for unit tests, TypeScript for types, ESLint for linting, and Prettier for formatting. The repo mantra is exactly this blunt: if you didn’t test it, it doesn’t work.

The gate is binary. The checks pass or the iteration is not done. If a check fails, the agent loops back inside the same iteration and fixes the code until it passes. The agent does not get to claim success while the test suite is red. This is what makes a commit in the git log trustworthy rather than aspirational.

Fix: screenshots for the things tests miss

Some failures do not show up in a unit test. A layout that is technically rendered but visually broken passes a DOM assertion and fails a human glance. For UI work, the loop takes a screenshot as part of completing a task, so the artifact you review in the morning includes proof of what the agent saw. A screenshot is a cheap, honest signal that catches the class of bugs that slip past assertions.

Sandbox escape and damage to your machine

Autonomous agents run in bypass-permissions mode, often called YOLO mode, because stopping to approve every file write would defeat the point of an overnight loop. Claude Code calls this --dangerously-skip-permissions. The flag name is honest. An agent with your permissions and no approval prompts can read your SSH keys, touch files outside the repo, run arbitrary install scripts, and make network calls you never intended. On your laptop, that is a real risk. The mistake is treating the agent’s good behavior as the safety boundary.

Fix: the sandbox is the boundary

Run the agent inside an isolated Docker Sandbox microVM. The boundary is the sandbox, not the agent’s restraint. ralph.sh does this by default through the sbx CLI, giving each run a deterministic sandbox name of the form ralph-<agent>-<current-dir>-<hash8>. Inside that microVM, the agent can run in YOLO mode because the worst it can damage is the sandbox.

You can inspect and operate the sandbox like any container:

sbx ls
sbx exec -it <name> bash

Network is deny-by-default. The agent gets only the domains you allow:

sbx policy allow network <name> registry.npmjs.org

That last point matters for both safety and cost. A deny-by-default network blocks exfiltration and stops an agent from wandering off to install or call something you did not sanction. The isolation model is documented in the Docker Sandboxes docs, and the bypass flag the loop relies on is in the Claude Code docs.

Failure modes mapped to guardrails

Here is the whole picture in one view: each failure on the left, each guardrail on the right.

flowchart LR
    subgraph Failures["Failure modes"]
        F1["Context rot"]
        F2["Runaway cost / infinite loop"]
        F3["Thrashing on a bad task"]
        F4["Silent wrong work"]
        F5["Sandbox damage"]
    end
    subgraph Guards["Guardrails"]
        G1["Fresh context + state on disk"]
        G2["-n cap + completion promise + budget"]
        G3["Atomic tasks, one per iteration, BLOCKED / DECIDE"]
        G4["Verification gates + screenshots"]
        G5["Docker Sandbox microVM"]
    end
    F1 --> G1
    F2 --> G2
    F3 --> G3
    F4 --> G4
    F5 --> G5

Read it as a contract. If you have turned on the guardrail, the matching failure mode is handled. If a run went wrong, find which guardrail was missing or misconfigured.

A pre-flight checklist before a long run

Before you start a multi-hour or overnight loop, walk this list. It is the difference between waking up to a clean branch and waking up to a mess.

Cap the iterations. Pass -n with a number you are willing to pay for. Do not run the uncapped one-liner.
Test the setup with one pass. Run ./ralph.sh --once and read the output before trusting a long run.
Check your tasks are atomic. Each task should be finishable in one iteration and verifiable by a check. If you cannot write the acceptance criteria, the task is not ready.
Confirm the verification stack runs. Make sure tests, lint, and type checking actually execute in the project, because the loop leans on them as its truth signal.
Run in the sandbox. Keep the agent inside the Docker Sandbox and the network on deny-by-default. Allow only the domains the build genuinely needs.
Pick the right agent and model. Switch agents with --agent and pass model flags after a separator:

./ralph.sh --agent codex -- --model gpt-5.5
./ralph.sh -a gemini -- --model pro

Supported agents are claude (the default), codex, copilot, cursor, gemini, and opencode.

The honest framing

A Ralph loop is persistence with a memory and a stop button. Its failure modes are the failure modes of any long autonomous process: it forgets, it overspends, it chases a bad goal, it lies to itself about success, and it can break things it touches. The technique does not pretend these do not exist. It pairs each one with a guardrail and makes the guardrails the default.

None of this removes your judgment from the loop. You still write the tasks, set the budget, and review the commits. What the guardrails buy you is the confidence to let an agent grind for hours without standing over it. Get the five right and the loop becomes boring in the best way: it either finishes, or it stops and tells you exactly why.

Frequently asked questions

What are the most common ways a Ralph loop fails?

There are five common failure modes: context rot where the agent loses the plot over a long session, runaway cost or infinite loops, thrashing on a task that is too big or too vague, silent wrong work that looks done but is broken, and damage from running an agent without a sandbox. Each one maps to a specific guardrail in ralph.sh.

How does a Ralph loop avoid context rot?

It resets the context window every iteration and stores project state on disk. Because the agent reads the task list, logs, and git history each pass instead of carrying a growing conversation, the window never gets large enough to rot. Progress lives in files like tasks.json and commits, not in chat memory.

How do I stop a Ralph loop from burning money?

Set an iteration cap with -n, rely on the completion promise so the loop stops the moment all tasks are done, and choose your model and budget before you start. The loop exits with code 1 when it hits the cap, which is a safety net rather than a failure. Running a single pass with --once first confirms the setup before a long run.

Why does my agent thrash instead of finishing the task?

Almost always because the task is too large or too vaguely specified to finish and verify in one iteration. The fix is atomic tasks, one task per invocation, and clear acceptance criteria. When a task is genuinely blocked or needs a decision, the agent should emit a BLOCKED or DECIDE promise and stop rather than guess.

Is it safe to run an autonomous coding agent in YOLO mode?

Only inside a sandbox. Bypass-permissions mode is dangerous on your laptop because the agent can read credentials and touch files outside the repo. Run it inside a Docker Sandbox microVM with deny-by-default networking, so the boundary is the sandbox rather than the agent's good behavior.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough

How to Write a PRD an AI Agent Can Actually Build From

Tue, 31 Mar 2026 00:00:00 GMT

A PRD an AI agent can build from is not a feature wishlist. It is three things in one document: goals (what to build and why), constraints (the stack, the boundaries, what is out of scope), and verifiable acceptance criteria (conditions the agent can check by running a command and reading the output). Drop any one of those and the agent fills the gap with a guess. The guess looks fine in the diff and breaks on the case nobody wrote down.

This post is the practical version: what goes in .agent/prd/PRD.md, what goes in the short SUMMARY.md the loop sends every iteration, how to draft both with the prd-creator skill, and how to write acceptance criteria an agent can actually verify. It assumes you already know the shape of spec-driven development with AI and want to write the document that sits at the top of it.

What a PRD for an AI agent actually is

A human PRD and an agent PRD overlap, but they are not the same document. A human reads a PRD, fills the gaps with judgment, and asks a teammate when something is unclear. An agent does none of that. It reads what is on disk, and when the spec is silent, it invents an answer and proceeds with full confidence. So the agent PRD has to do more work up front.

Three properties decide whether a PRD is buildable.

Goals are concrete, not aspirational. “Make onboarding delightful” is not a goal an agent can build toward. “A new user reaches the dashboard in three steps or fewer after submitting the signup form” is. State the outcome in terms something can observe.

Constraints are explicit. Name the framework, the data store, the auth approach, and the libraries you have already committed to. Name what is out of scope just as clearly. An out-of-scope section is a fence: without it, an agent on a long run happily adds a feature you never asked for and now have to maintain.

Acceptance criteria are verifiable. Each criterion is a condition the agent can confirm by running a test, hitting an endpoint, or reading a file. “Login works” is a vibe. “POST /api/login with a wrong password returns 401 and the body { error: 'Invalid credentials' }” is a criterion. The difference is whether a machine can return a yes or a no without your opinion.

The reason this matters more for agents than for people: an autonomous loop amplifies whatever you feed it. Feed it ambiguity and it amplifies ambiguity across every iteration. The Ralph technique runs an agent against your task list until the work is done, and the whole design rests on the agent rebuilding its understanding from files on each pass. If you want the mechanics of that loop, start with what is the Ralph technique. The PRD is the document the entire loop reads from.

Where the PRD lives: PRD.md and SUMMARY.md

Ralph keeps the product specification in two files under .agent/prd/, and the split is deliberate.

PRD.md is the full document. It is for depth: a human reads it once to understand the project, and the agent reads it when it needs detail it cannot get from the summary. The prd-creator skill writes it with a consistent set of sections:

App overview and objectives
Target audience
Success metrics and KPIs
Competitive analysis
Core features and user flows
Technical stack
Prerequisites and access
Security considerations
Assumptions and dependencies

SUMMARY.md is the short executive overview. This is the file that gets sent to the agent every iteration so it reorients fast without rereading the entire PRD. It contains an overall description of the project, the main features, the key user flows, and a short list of key requirements. Nothing more.

The economics drive the split. Every iteration starts the agent with a fresh context window, and tokens in that window cost money and attention. You do not want to spend that budget reloading a 3000 word PRD on every pass when a tight summary reorients the agent just as well. Long PRD for depth, short summary for the working context on every iteration.

flowchart LR
  Reqs["Unstructured requirements"] --> Interview["prd-creator interview, plan mode"]
  Interview --> PRD["prd/PRD.md: goals, constraints, criteria"]
  PRD --> Summary["prd/SUMMARY.md: short overview, sent each iteration"]
  PRD --> Tasks["tasks.json and tasks/TASK-ID.json"]
  Summary --> Loop["ralph.sh loop, fresh context each iteration"]
  Tasks --> Loop
  Loop --> Verify["Run tests, lint, types, screenshot"]
  Verify --> Commit["Commit, set passes true"]

The PRD feeds two children. The summary is the version the loop reads constantly. The task list is the executable decomposition. Get the PRD right and both children inherit clear goals and criteria. Get it vague and both inherit the vagueness.

Draft it with the prd-creator skill in plan mode

You do not write all of this by hand. Ralph ships a prd-creator skill that turns unstructured requirements into a PRD plus a task list. Run it in plan mode, where the agent is read-only and focused on asking questions instead of writing code. Plan mode matters here: you want the agent interrogating your idea, not racing ahead to scaffold files before the spec exists.

The flow is a conversation, not a one shot. The instinct most people have is to paste a paragraph and expect a finished plan. The skill instead pushes back. It interviews you to fill the gaps, asking clarifying questions one at a time, and it researches the competitive landscape before it commits anything to PRD.md. When a question can be answered by reading the codebase, it reads the codebase instead of asking you.

A prompt to kick it off looks like plain language:

Use the prd-creator skill in plan mode. I want to build a link shortener
with accounts, custom slugs, and click analytics. Interview me, write the
PRD to .agent/prd/PRD.md and the summary to .agent/prd/SUMMARY.md, then
generate the task list in .agent/tasks.json.

During the interview, the skill also verifies prerequisites and creates or updates .env.local with placeholder values only. It never writes a real secret to the PRD, the tasks, the logs, or .env.local. You fill the real values in by hand. This is the moment the spec records what credentials and access the project needs, so the agent is not discovering halfway through a 50 task run that it never had database access.

When it finishes, you have PRD.md, SUMMARY.md, and tasks.json with one TASK-{ID}.json spec per task. From there you run the loop:

npx @pageai/ralph-loop
./ralph.sh -n 50

You can amend later. When you want to add a feature or fix a bug mid-project, run the skill again to update the PRD and append tasks. The spec grows with the project instead of going stale the moment you start coding.

Write acceptance criteria the agent can verify

This is the part that separates a PRD an agent can build from a PRD that produces confident nonsense. An acceptance criterion is only useful if the agent can check it without you. The test is simple: can the agent confirm this by running something and reading the output? If not, rewrite it.

Three rules make a criterion verifiable.

Name the input and the expected output. Vague: “the endpoint validates email.” Verifiable: “POST /api/register with email ‘not-an-email’ returns 400 and the body { error: 'Please enter a valid email' }.” Now the agent can send the request, read the status and body, and compare.

Point at an observable artifact. “Passwords are secure” is unprovable. “The stored password starts with the bcrypt prefix $2b$ and never equals the plaintext value” can be confirmed by reading the row. Anchor the criterion to something the agent can inspect: a database row, a response header, a file on disk, a console exit code.

Make it pass or fail, never partial. A criterion that needs interpretation is a criterion the agent will interpret in its favor. “The UI looks clean” invites argument. “The submit button is disabled until both fields are non-empty” does not.

In Ralph, the criteria do not float in the PRD. They land in the per-task spec files. Each TASK-{ID}.json carries an acceptanceCriteria array, and the tests that prove those criteria are steps inside the task, not separate tasks scheduled for later.

{
  "id": "TASK-3",
  "title": "POST /api/auth/register creates a new user account",
  "category": "api-endpoint",
  "description": "Validate input, hash the password, store the user, return a success response.",
  "acceptanceCriteria": [
    "POST with valid email and password returns 201 with the user id and email",
    "Invalid email format returns 400 with the error text Please enter a valid email",
    "Password shorter than 8 characters returns 400",
    "Duplicate email returns 409, not a generic 500",
    "The stored password starts with $2b$ and is never the plaintext value"
  ],
  "steps": [
    {
      "step": 1,
      "description": "Add the register route handler",
      "details": "Validate with a zod schema, hash with bcrypt, insert into users.",
      "pass": false
    },
    {
      "step": 2,
      "description": "Write Vitest cases for every acceptance criterion",
      "details": "Cover valid registration, invalid email, short password, duplicate email, and the stored hash prefix.",
      "pass": false
    }
  ],
  "dependencies": ["TASK-1", "TASK-2"],
  "estimatedComplexity": "medium"
}

Every line in acceptanceCriteria maps to something the verification stack can confirm. The loop assumes that stack: Playwright for end to end, Vitest for unit tests, TypeScript for types, ESLint for lint, Prettier for format. The repo mantra is blunt: if you didn’t test it, it doesn’t work. The agent runs the gate, and only after it passes does it flip passes to true, take a screenshot, and commit. Turning criteria into atomic, independently verifiable packets like this is its own discipline, covered in breaking a PRD into atomic agent tasks.

Name env vars, libraries, and user flows so the agent does not guess

The fastest way to get an agent to invent something wrong is to leave a decision implicit. Three categories cause the most trouble, and the PRD should pin all three.

Environment variables. List every variable the project reads, with a one line note on what each is for. The prd-creator skill writes placeholders into .env.local during prerequisite verification, so the agent knows the keys exist without ever seeing a real secret. Without this, an agent guesses variable names, scatters them across files, and you spend the morning reconciling DATABASE_URL against DB_CONNECTION_STRING.

Libraries and the stack. Say which framework, which ORM, which validation library, which test runner. If the project already uses zod, the PRD should say so, or the agent will reach for whatever it saw most recently in its training and add a second validation library next to your first. Naming the stack is also where you encode reuse: tell the agent to extend the existing auth module rather than write a parallel one.

User flows. A flow is a sequence of steps with branches, and the branches are where agents guess. “Users can reset their password” hides a dozen decisions. Does the reset link expire? After how long? What happens on an expired link? Does requesting a reset for an unknown email reveal that the account does not exist? Write the flow as steps and edge cases, and each edge case becomes an acceptance criterion instead of a surprise in production.

The pattern across all three: every decision you leave out is a decision the agent makes for you, silently, at the moment it is most expensive to change. The PRD is where you make those decisions while they are still cheap.

A short worked example

Take the link shortener from the prompt above and watch the three properties show up.

The goal is concrete: “an authenticated user creates a short link with an optional custom slug and sees total clicks per link.” Not “build a great link tool.” The constraint section names the stack and fences the scope: custom domains and team accounts are out of scope for version one. The acceptance criteria get specific per feature. For slug generation: “a generated slug is 7 characters of base62” and “a collision retries up to 3 times before returning an error.” For the redirect: “GET /:slug on an unknown slug returns 404” and “a valid slug records exactly one click row and issues a 302 to the target URL.”

The prd-creator interview is where these get extracted. Are slugs unique globally or per account? What happens on a collision? Do analytics count unique visitors or raw hits? Each answer becomes a line in the PRD, and the unanswered questions become the edge cases that would otherwise blow up the loop. By the time the PRD is approved, the ambiguity is gone, and the task list inherits criteria a machine can check. The loop then runs one task at a time, which is the rule that keeps a long run from drifting, explained in one task per iteration.

The framing of phases here (specify intent, plan the approach, decompose into tasks, implement and verify) comes from GitHub Spec Kit, and the loop that runs it autonomously was popularized by Geoffrey Huntley in his original Ralph writeup. The PRD is the artifact the first phase produces and every later phase consumes.

Where to go next

If you are writing the spec that drives a loop, read down through the spec-driven cluster:

Spec-driven development with AI for the full Specify, Plan, Tasks, Implement workflow this PRD sits inside.
Breaking a PRD into atomic agent tasks for turning the PRD into independently verifiable packets.
One task per iteration for the rule that keeps long runs reliable.

For the mechanics of the loop that reads your PRD on every pass, the fresh-context design, and where the technique came from, read what is the Ralph technique.

Frequently asked questions

What makes a PRD buildable by an AI agent rather than a person?

A buildable PRD states concrete goals, explicit constraints, and verifiable acceptance criteria. A person can fill gaps with judgment and ask a teammate, but an agent invents an answer whenever the spec is silent. So the agent PRD must name the stack, fence what is out of scope, and define each acceptance criterion as a condition a machine can confirm by running a command and reading the output.

What is the difference between PRD.md and SUMMARY.md in Ralph?

PRD.md is the full document with app overview, target audience, success metrics, core features and user flows, technical stack, prerequisites, security considerations, and assumptions. SUMMARY.md is a short executive overview with the main features, key user flows, and key requirements. The summary is what gets sent to the agent every iteration so it reorients fast without rereading the entire PRD.

How do I write acceptance criteria an agent can verify?

Name the input and the expected output, point at an observable artifact, and make every criterion pass or fail with no interpretation. For example, POST with an invalid email returns 400 with a specific error text, or the stored password starts with the bcrypt prefix and is never the plaintext value. The agent confirms each one with Playwright, Vitest, type checks, and lint before it marks the task done.

How do I create the PRD without writing it all by hand?

Use the prd-creator skill in plan mode. It interviews you one question at a time, researches the competitive landscape, verifies prerequisites, and writes placeholder values into .env.local without ever storing a real secret. It then writes PRD.md and SUMMARY.md and generates tasks.json with a prerequisite verification task first. You can run it again later to amend the PRD and append tasks.

Why does naming env vars, libraries, and user flows matter so much?

Every decision left implicit is a decision the agent makes for you, silently, at the moment it is most expensive to change. If you do not name the validation library, the agent may add a second one. If you do not spell out the password reset flow, it guesses how expiry and unknown emails behave. Listing variables, the stack, and flows with their edge cases turns those guesses into acceptance criteria.

Run your own Ralph loop

Ralph is a hackable script you point at your project. Install it and let an agent work through your task list.

npx @pageai/ralph-loop

Install from npm Star on GitHub Watch the walkthrough