Skip to content
Back to search

ralph-loop

A long-running AI agent loop. Ralph automates software development tasks by iteratively working through a task list until completion.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pageai-pro-ralph-loop/badge.svg)](/listings/pageai-pro-ralph-loop)

HTML

<a href="/listings/pageai-pro-ralph-loop"><img src="/api/listings/pageai-pro-ralph-loop/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

(Optional) Set up code base

I recommend using a CLI to bootstrap your project with the necessary tools and dependencies, e.g.:

# for a Tanstack app:
npx @tanstack/cli create lib --add-ons eslint,form,tanstack-query,nitro --no-git

# or for a Next.js app
npx create-next-app@latest my-app --typescript --tailwind --eslint --app

> If you must start from a blank slate, which is not recommended, see [Starting from scratch](#starting-from-scratch). You can also go for a more barebone start by running `npx create-vite@latest src --template react-ts`

1️⃣ Step 1: Install Ralph

Run this in your project's directory to install Ralph.

npx @pageai/ralph-loop

> Docs: [ralphloop.sh](https://ralphloop.sh)

2️⃣ Step 2: Create a PRD + task list

Use the `prd-creator` skill to generate a PRD from your requirements.<br/> Open up Claude Code or Cursor etc., **switch to plan mode**, and prompt it with **your requirements**. Like so:

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.
- Target audience: Small business owners and freelancers.
- Core features:
  - Track income and expenses.
  - Create and send invoices.
  - Track payments and receipts.
  - Generate reports and insights.
  - Connect to bank accounts and credit cards.
  - Connect to accounting software.
  - Connect to payment processors.
- Use the shadcn/ui library for components.
- Integrate with Stripe for payments.
- Use Supabase for database.
- You can find env variables in the .env.example file: SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, STRIPE_SECRET_KEY, etc. are available in the runtime.

// etc.

> Check out [the video](https://www.youtube.com/watch?v=3TL8Ez66I3o&t=403s) for a more realistic example on how to write requirements.

<details> <summary><strong>✨ Pro tips</strong></summary>

- mention libraries and frameworks you want to use - mention env variables, e.g. for DB, 3rd party API keys, etc. Store them in `.env` and add it to **.gitignore** - describe user flows and journeys - add relevant docs and UI references if applicable inside `/docs` and mention them in the requirements - be as descriptive as possible - *it's fine to write in your own language*

</details> <br/>

Then, follow the Skill's instructions and verify the PRD and then tasks.<br/> **It is highly recommended that you review individual task requirements before starting the loop. Review EACH TASK INDIVIDUALLY.**

3️⃣ Step 3: Set up the agent inside Docker Sandboxes

Install and sign in to Docker Sandboxes first. See Docker's [AI overview](https://docs.docker.com/ai-overview/) and [Docker Sandboxes docs](https://docs.docker.com/ai/sandboxes/) for the official setup flow.

Authenticate your chosen Docker Sandboxes agent before running Ralph. Claude is the default:

./ralph.sh --login

Ralph prints all supported login commands, then opens the selected agent inside the correctly named sandbox. To log in to a different supported agent, pass `--agent`:

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

Follow the instructions to log in to that agent. Ralph names sandboxes as `ralph-<agent>-<current-dir>-<hash8>`, for example `ralph-claude-my-app-a1b2c3d4`. To print the exact sandbox name without starting the loop, run:

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

Once the sandbox exists (after the first `--login` or after Ralph runs at least once), publish your dev server port to the host with `./ralph.sh --ports`. The port is captured from the dev-server URL you set during install and stored in `RALPH_DEFAULT_PORTS` in `ralph.sh`:

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

👉 Answer "Yes" to `Bypass Permissions mode`, that's the exact reason why you are using the Docker sandbox.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 623 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # A Ralph Wiggum Loop implementation that works™
  2. [![@pageai/ralph-loop version](https://img.shields.io/npm/v/@pageai/ralph-loop?label=npm&style=flat)](https://www.npmjs.com/package/@pageai/ralph-loop)
  3. 📚 Full docs: [ralphloop.sh](https://ralphloop.sh)
  4. Ralph is a long-running AI agent loop. Ralph automates software development tasks by iteratively working through a task list until completion. This allows for long running agent loops, effectively enabling AI to code for days at a time.
  5. This is an implementation that actually works, containing a hackable script so you can configure it to your env and favorite agentic AI CLI. It's set up by default to use Claude Code in Docker Sandboxes, and supports [multiple Docker Sandboxes agents](#running-with-a-different-agentic-cli).
  6. #### 👉 [Watch the video](https://www.youtube.com/watch?v=3TL8Ez66I3o) for an in-depth walkthrough.
  7. [![Ralph Wiggum Loop](https://github.com/user-attachments/assets/be94b8ba-b073-489d-b07e-d11db975a907)](https://www.youtube.com/watch?v=3TL8Ez66I3o)
  8. - [Getting Started](#getting-started)
  9. - [(Optional) Set up code base](#optional-set-up-code-base)
  10. - [1️⃣ Step 1: Install Ralph](#1️⃣-step-1-install-ralph)
  11. - [2️⃣ Step 2: Create a PRD + task list](#2️⃣-step-2-create-a-prd--task-list)
  12. - [3️⃣ Step 3: Set up the agent inside Docker Sandboxes](#3️⃣-step-3-set-up-the-agent-inside-docker-sandboxes)
  13. - [4️⃣ Step 4: Run Ralph](#4️⃣-step-4-run-ralph)
  14. - [Running the Ralph Loop with custom options](#running-the-ralph-loop-with-custom-options)
  15. - [(Optional) Adjusting to your language/framework](#optional-adjusting-to-your-languageframework)
  16. - [How It Works](#how-it-works)
  17. - [How Is This Different from Other Ralphs?](#how-is-this-different-from-other-ralphs)
  18. - [Steering the Agent](#steering-the-agent)
  19. - [Support](#support)
  20. - [Promise Tags](#promise-tags)
  21. - [Exit Codes](#exit-codes)
  22. - [Structure](#structure)
  23. - [Continued Development](#continued-development)
  24. - [Skills](#skills)
  25. - [Available Skills](#available-skills)
  26. - [Skills Directory Structure](#skills-directory-structure)
  27. - [Reference](#reference)
  28. - [Docker Sandboxes](#docker-sandboxes)
  29. - [Playwright configuration](#playwright-configuration)
  30. - [Vitest configuration](#vitest-configuration)
  31. - [Running with a different agentic CLI](#running-with-a-different-agentic-cli)
  32. - [Starting from scratch](#starting-from-scratch)
  33. - [Debugging](#debugging)
  34. - [How to inspect the sandbox and debug](#how-to-inspect-the-sandbox-and-debug)
  35. - [Allowing network access](#allowing-network-access)
  36. - [Authentication issues in Sandboxes / Login not persisting](#authentication-issues-in-sandboxes--login-not-persisting)
  37. - [License](#license)
  38. ---------------------------------
  39. ## Getting Started
  40. ### (Optional) Set up code base
  41. I recommend using a CLI to bootstrap your project with the necessary tools and dependencies, e.g.:
  42. ```bash
  43. # for a Tanstack app:
  44. npx @tanstack/cli create lib --add-ons eslint,form,tanstack-query,nitro --no-git
  45. # or for a Next.js app
  46. npx create-next-app@latest my-app --typescript --tailwind --eslint --app
  47. ```
  48. > If you must start from a blank slate, which is not recommended, see [Starting from scratch](#starting-from-scratch). You can also go for a more barebone start by running `npx create-vite@latest src --template react-ts`
  49. ### 1️⃣ Step 1: Install Ralph
  50. Run this in your project's directory to install Ralph.
  51. ```bash
  52. npx @pageai/ralph-loop
  53. ```
  54. > Docs: [ralphloop.sh](https://ralphloop.sh)
  55. ### 2️⃣ Step 2: Create a PRD + task list
  56. Use the `prd-creator` skill to generate a PRD from your requirements.<br/>
  57. Open up Claude Code or Cursor etc., **switch to plan mode**, and prompt it with **your requirements**. Like so:
  58. ```
  59. Use the prd-creator skill to help me create a PRD and task list for the below requirements.
  60. An app is already set up with React, Tailwind CSS and TypeScript.
  61. Requirements:
  62. - A SaaS product that helps users manage their finances.
  63. - Target audience: Small business owners and freelancers.
  64. - Core features:
  65. - Track income and expenses.
  66. - Create and send invoices.
  67. - Track payments and receipts.
  68. - Generate reports and insights.
  69. - Connect to bank accounts and credit cards.
  70. - Connect to accounting software.
  71. - Connect to payment processors.
  72. - Use the shadcn/ui library for components.
  73. - Integrate with Stripe for payments.
  74. - Use Supabase for database.
  75. - You can find env variables in the .env.example file: SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, STRIPE_SECRET_KEY, etc. are available in the runtime.
  76. // etc.
  77. ```
  78. > Check out [the video](https://www.youtube.com/watch?v=3TL8Ez66I3o&t=403s) for a more realistic example on how to write requirements.
  79. <details>
  80. <summary><strong>✨ Pro tips</strong></summary>
  81. - mention libraries and frameworks you want to use
  82. - mention env variables, e.g. for DB, 3rd party API keys, etc. Store them in `.env` and add it to **.gitignore**
  83. - describe user flows and journeys
  84. - add relevant docs and UI references if applicable inside `/docs` and mention them in the requirements
  85. - be as descriptive as possible
  86. - *it's fine to write in your own language*
  87. </details>
  88. <br/>
  89. Then, follow the Skill's instructions and verify the PRD and then tasks.<br/>
  90. **It is highly recommended that you review individual task requirements before starting the loop. Review EACH TASK INDIVIDUALLY.**
  91. ### 3️⃣ Step 3: Set up the agent inside Docker Sandboxes
  92. Install and sign in to Docker Sandboxes first. See Docker's [AI overview](https://docs.docker.com/ai-overview/) and [Docker Sandboxes docs](https://docs.docker.com/ai/sandboxes/) for the official setup flow.
  93. Authenticate your chosen Docker Sandboxes agent before running Ralph. Claude is the default:
  94. ```bash
  95. ./ralph.sh --login
  96. ```
  97. Ralph prints all supported login commands, then opens the selected agent inside the correctly named sandbox. To log in to a different supported agent, pass `--agent`:
  98. ```bash
  99. ./ralph.sh --login --agent codex
  100. ```
  101. Follow the instructions to log in to that agent. Ralph names sandboxes as `ralph-<agent>-<current-dir>-<hash8>`, for example `ralph-claude-my-app-a1b2c3d4`. To print the exact sandbox name without starting the loop, run:
  102. ```bash
  103. ./ralph.sh --print-name
  104. ./ralph.sh --print-name --agent cursor
  105. ```
  106. Once the sandbox exists (after the first `--login` or after Ralph runs at least once), publish your dev server port to the host with `./ralph.sh --ports`. The port is captured from the dev-server URL you set during install and stored in `RALPH_DEFAULT_PORTS` in `ralph.sh`:
  107. ```bash
  108. ./ralph.sh --ports
  109. ./ralph.sh --ports --agent codex
  110. ```
  111. 👉 Answer "Yes" to `Bypass Permissions mode`, that's the exact reason why you are using the Docker sandbox.
  112. > **Alternative: API keys** — you can configure API keys for supported agents instead of interactive login, but this is usually more expensive and not recommended. See Docker's [supported agents docs](https://docs.docker.com/ai/sandboxes/agents/) for per-agent setup details.
  113. > If you want to use a different agentic CLI, see [Running with a different agentic CLI](#running-with-a-different-agentic-cli).
  114. ### 4️⃣ Step 4: Run Ralph
  115. ```bash
  116. ./ralph.sh -n 50 # Run Ralph Loop with 50 iterations
  117. ```
  118. > ✍️ Note: the first iteration will be spent on ensuring the named sandbox environment is set up correctly. Expect 5 minutes to complete.
  119. ## Running the Ralph Loop with custom options
  120. ```bash
  121. # Run the agent loop (default: 10 iterations)
  122. ./ralph.sh
  123. # Run with custom iteration limit
  124. ./ralph.sh 5
  125. ./ralph.sh -n 5
  126. ./ralph.sh --max-iterations 5
  127. # Run exactly one iteration
  128. ./ralph.sh --once
  129. # Run with a different supported agent
  130. ./ralph.sh --agent codex
  131. ./ralph.sh -a cursor -n 5
  132. # Log in to an agent inside Ralph's deterministic sandbox
  133. ./ralph.sh --login
  134. ./ralph.sh --login --agent cursor
  135. # Publish the configured dev port to the selected agent sandbox
  136. ./ralph.sh --ports
  137. ./ralph.sh --ports --agent codex
  138. # Print the deterministic sandbox name
  139. ./ralph.sh --print-name
  140. ./ralph.sh --print-name --agent codex
  141. # Pass extra options to the selected agent
  142. ./ralph.sh --agent codex -- --model gpt-5.5
  143. ./ralph.sh -a gemini -- --model pro
  144. # Show help
  145. ./ralph.sh --help
  146. ```
  147. > NB: you might need to run `chmod +x ralph.sh` to make the script executable.
  148. > The default "mode" is "implementation". Depending on your use case, you might want to change `.agent/PROMPT.md` to a different mode, e.g. "refactor", "review", "test" etc.
  149. ⚠️ If you want to use a different language or testing framework, see below.
  150. ### (Optional) Adjusting to your language/framework
  151. This script assumes the following are installed:
  152. - [Playwright](https://playwright.dev/) for e2e testing
  153. - [Vitest](https://vitest.dev/) for unit testing
  154. - [TypeScript](https://www.typescriptlang.org/) for type checking
  155. - [ESLint](https://eslint.org/) for linting
  156. - [Prettier](https://prettier.io/) for formatting
  157. If you'd like to use a different language, testing framework etc. please adjust `.agent/PROMPT.md` to reflect your setup, server ports and startup commands etc.
  158. 👉 The loop is controlled by this prompt, which will be sent to the agent each iteration.
  159. ---------------------------------
  160. ## How It Works
  161. Each iteration, Ralph will:
  162. 1. Find the highest-priority incomplete task from `.agent/tasks.json`
  163. 2. Work through the task steps defined in `.agent/tasks/TASK-{ID}.json`
  164. 3. Run tests, linting, and type checking
  165. 4. Complete task, take screenshot, update task status and commit changes
  166. 5. Repeat until all tasks pass or max iterations reached
  167. ## How Is This Different from Other Ralphs?
  168. This was kept hackable so you can make it your own.<br/>
  169. The script follows the original concepts of the Ralph Wiggum Loop, working with fresh contexts and providing clear verifiable feedback.
  170. It also works generically with any task set.
  171. <details>
  172. <summary><strong>✨ Features</strong></summary>
  173. - **PRD generation** - Creates a PRD and task list from requirements
  174. - **Task lookup table generation** - Creates a task lookup table from the PRD
  175. - **Task breakdown + step generation** - Breaks down each task into manageable steps
  176. - **Iteration tracking** - Shows progress through iterations with timing
  177. - **Stream preview** - Shows live output from the Agent
  178. - **Step detection** - Identifies current activity (Thinking, Implementing, Testing, etc.)
  179. - **Screenshot capture** - Captures a screenshot of the current screen
  180. - **Notifications** - Alerts when human input is needed
  181. - **History logging** - Saves clean output from each iteration
  182. - **Timing** - Shows timing metrics for each iteration and total time
  183. - **Steering** - Allows prioritizing critical work that needs to be done before the loop can continue
  184. </details>
  185. <br/>
  186. Besides that:
  187. - it allows you to dump unstructured requirements and have the agent create a PRD and task list for you.
  188. - it uses a task lookup table with individual detailed steps → more scalable as you get 100s of tasks done.
  189. - it's sandboxed and more secure
  190. - it shows progress and stats so you can keep an eye on what's been done
  191. - it instructs the agent to write and run automated tests and screenshots per task
  192. - it provides observability and traceability of the agent's work, showing a stream of output and capturing full historical logs per iteration
  193. ## Steering the Agent
  194. In some cases, you might notice the agent is having trouble, slowed down or struggling to overcome a blocker.
  195. While the loop is running, you can edit the `.agent/STEERING.md` file to add critical work that needs to be done before the loop can continue.
  196. The agent will check this file each iteration and if it finds any critical work, it will skip tasks and complete the critical work first.
  197. ## Support
  198. The `ralph.sh` script is designed to be hackable.
  199. It is configured to use Claude Code in Docker Sandboxes by default, and you can select another supported agent with `--agent`.
  200. Each run uses a deterministic sandbox name in the form `ralph-<agent>-<current-dir>-<hash8>`, so different agents get separate sandboxes for the same project. On exit or double Ctrl+C, Ralph stops only the named sandbox for the current invocation.
  201. > NB: skills are supported by all major agentic AI CLIs via symlinks.
  202. ### Promise Tags
  203. Ralph uses semantic tags to communicate status:
  204. - `<promise>COMPLETE</promise>` - All tasks finished successfully
  205. - `<promise>BLOCKED:reason</promise>` - Agent needs human help
  206. - `<promise>DECIDE:question</promise>` - Agent needs a decision
  207. ### Exit Codes
  208. | Code | Meaning |
  209. | ---- | ------------------------------ |
  210. | 0 | COMPLETE - All tasks finished |
  211. | 1 | MAX_ITERATIONS - Reached limit |
  212. | 2 | BLOCKED - Needs human help |
  213. | 3 | DECIDE - Needs human decision |
  214. ## Structure
  215. ```
  216. .agent/
  217. ├── PROMPT.md # Prompt sent to Agent each iteration
  218. ├── tasks.json # Task lookup table (required)
  219. ├── tasks/ # Individual task specs (TASK-{ID}.json)
  220. ├── prd/
  221. │ ├── PRD.md # Product requirements document
  222. │ └── SUMMARY.md # Short project overview sent to Agent each iteration
  223. ├── logs/
  224. │ └── LOG.md # Progress log (auto-created)
  225. ├── history/ # Iteration output logs
  226. └── skills/ # Shared skills (source of truth)
  227. ```
  228. ## Continued Development
  229. As Ralph implements tasks, you might notice that you want some tweaks, features or even bug fixes.<br/>
  230. To do so, you need to continue using the `prd-creator` skill to update the PRD and task list.
  231. For example:
  232. ```
  233. I would like to expand the PRD. Use the prd-creator skill to create these tasks:
  234. - there is a bug in X that should be fixed by doing Y
  235. - create a new feature that implement Z
  236. etc.
  237. ```
  238. It's fine to add multiple tasks at once.
  239. ## Skills
  240. Skills are reusable agent capabilities that provide specialized knowledge and workflows. The canonical source is `.agent/skills/`, which is symlinked to multiple agent tool directories for compatibility.
  241. ### Available Skills
  242. | Skill | Description |
  243. | ----------------------------- | ------------------------------------------------------- |
  244. | `agent-browser` | Browser automation for web apps and desktop apps |
  245. | `component-refactoring` | Patterns for splitting and refactoring React components |
  246. | `e2e-tester` | End-to-end testing workflows |
  247. | `frontend-code-review` | Code quality and performance review guidelines |
  248. | `frontend-testing` | Unit and integration testing patterns |
  249. | `mysql` | MySQL/InnoDB schema, indexing, query tuning, and ops |
  250. | `postgres` | PostgreSQL best practices and query optimization |
  251. | `prd-creator` | Create PRDs and task breakdowns for Ralph |
  252. | `shadcn` | Manage shadcn components, registries, and UI composition |
  253. | `skill-creator` | Create new skills |
  254. | `vercel-react-best-practices` | React/Next.js performance patterns |
  255. | `vitest-best-practices` | Vitest structure, assertions, mocks, async tests, and performance |
  256. | `web-design-guidelines` | UI/UX design principles |
  257. ### Skills Directory Structure
  258. Skills are symlinked from `.agent/skills/` to multiple locations for cross-tool compatibility:
  259. ```
  260. # Source of truth
  261. .agent/skills/
  262. ├── component-refactoring/
  263. ├── e2e-tester/
  264. ├── postgres/
  265. ├── ...
  266. # Symlinks -> .agent/skills/*
  267. .agents/skills/*
  268. .claude/skills/*
  269. .codex/skills/*
  270. .cursor/skills/*
  271. ```
  272. ## Reference
  273. ### Docker Sandboxes
  274. Docker Sandboxes runs coding agents in isolated microVMs. Ralph uses the standalone `sbx` CLI and starts agents with a deterministic `--name` so the sandbox can be reused and stopped cleanly.
  275. Use `./ralph.sh --login` to authenticate inside the correct named sandbox. Use `./ralph.sh --print-name` if you only need the deterministic sandbox name for debugging.
  276. Useful Docker references:
  277. - [Docker AI overview](https://docs.docker.com/ai-overview/) explains how Docker Sandboxes fits with Gordon, Model Runner, MCP Toolkit, and Docker Agent.
  278. - [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) covers installation, usage, security, credentials, and troubleshooting.
  279. - [Supported Docker Sandboxes agents](https://docs.docker.com/ai/sandboxes/agents/) lists the agent CLIs Docker supports.
  280. ### Playwright configuration
  281. If you are using Playwright, here is a recommended configuration:
  282. ```typescript:playwright.config.ts
  283. import { defineConfig, devices } from '@playwright/test';
  284. /**
  285. * See https://playwright.dev/docs/test-configuration.
  286. */
  287. export default defineConfig({
  288. testDir: './tests',
  289. fullyParallel: true,
  290. globalTimeout: 30 * 60 * 1000,
  291. forbidOnly: !!process.env.CI,
  292. retries: process.env.CI ? 2 : 1,
  293. workers: process.env.CI ? 3 : 6,
  294. reporter: 'html',
  295. use: {
  296. baseURL: 'http://localhost:3000',
  297. trace: 'on-first-retry',
  298. },
  299. // NB: only chromium will run in Docker (arm64).
  300. projects: [
  301. {
  302. name: 'chromium',
  303. use: { ...devices['Desktop Chrome'] },
  304. }
  305. ],
  306. });
  307. ```
  308. ### Vitest configuration
  309. If you are using Vitest, here is a recommended configuration:
  310. ```typescript:vitest.config.ts
  311. import { defineConfig } from "vitest/config";
  312. import react from "@vitejs/plugin-react";
  313. import path from "path";
  314. export default defineConfig({
  315. plugins: [react()],
  316. test: {
  317. environment: "node",
  318. globals: true,
  319. include: ["lib/**/*.test.ts", "lib/**/*.test.tsx"],
  320. // setupFiles: ['./vitest.setup.ts'], // Include this if using Next.js
  321. },
  322. resolve: {
  323. alias: {
  324. "@": path.resolve(__dirname),
  325. },
  326. },
  327. });
  328. ```
  329. If you are using Next.js, you'll also need a `vitest.setup.ts` file to mock the `next/image` and `next/link` components.
  330. ```typescript:vitest.setup.ts
  331. import '@testing-library/jest-dom/vitest'
  332. import { vi } from 'vitest'
  333. import React from 'react'
  334. // If using Next.js, mock next/image
  335. vi.mock('next/image', () => ({
  336. default: ({ src, alt, ...props }: { src: string; alt: string }) => {
  337. return React.createElement('img', { src, alt, ...props })
  338. },
  339. }))
  340. // If using Next.js, mock next/link
  341. vi.mock('next/link', () => ({
  342. default: ({
  343. children,
  344. href,
  345. ...props
  346. }: {
  347. children: React.ReactNode
  348. href: string
  349. }) => {
  350. return React.createElement('a', { href, ...props }, children)
  351. },
  352. }))
  353. ```
  354. ### Running with a different agentic CLI
  355. Ralph can run several Docker Sandboxes agents without editing the script:
  356. ```bash
  357. ./ralph.sh --agent claude # default
  358. ./ralph.sh --agent codex
  359. ./ralph.sh --agent copilot
  360. ./ralph.sh --agent cursor
  361. ./ralph.sh --agent gemini
  362. ./ralph.sh --agent opencode
  363. ```
  364. You can also pass agent-specific options after Ralph's `--` separator:
  365. ```bash
  366. ./ralph.sh --agent codex -- --model gpt-5.3-codex
  367. ./ralph.sh --agent gemini -- --model pro
  368. ```
  369. Ralph currently supports: `claude`, `codex`, `copilot`, `cursor`, `gemini`, and `opencode`.
  370. See Docker's full list of supported agentic AI CLIs in [Docker's docs](https://docs.docker.com/ai/sandboxes/agents/).
  371. Because the agent name is part of Ralph's sandbox name, switching agents creates or reuses that agent's own sandbox for the project.
  372. ### Starting from scratch
  373. For AI to actually verify its implementation and for the loop to work, you need a way to verify it.
  374. To that end, at the minimum you'll need an end-to-end test framework and a unit test framework.
  375. For example, you can use the following commands to install Playwright and Vitest:
  376. ```bash
  377. npm i @playwright/test vitest jsdom typescript eslint prettier -D
  378. # If using React, also recommend installing:
  379. npm i @vitejs/plugin-react @testing-library/dom @testing-library/jest-dom @testing-library/react @testing-library/user-event -D
  380. ```
  381. It is recommended that you add skills for your specific language and framework. See [skills.sh](https://skills.sh) to discover existing skills.
  382. ## Debugging
  383. ### How to inspect the sandbox and debug
  384. You might be wondering... if this is not a Docker container, how can you see what's going on inside Docker!?
  385. How to debug/install things?
  386. That's quite straightforward.
  387. You first need to run:
  388. ```bash
  389. sbx ls
  390. ```
  391. Note down the name of the sandbox for the agent you ran, e.g. `ralph-claude-my-app-a1b2c3d4`. Ralph also prints this name when it starts.
  392. And then you can run bash into any of the sandboxes like so:
  393. ```bash
  394. sbx exec -it <sandbox-name> bash # e.g. sbx exec -it ralph-claude-my-app-a1b2c3d4 bash
  395. ```
  396. And you have full control over the sandbox, just like a regular container. You can install packages, run commands, etc.
  397. You can also run the agent CLI inside the sandbox (make sure to navigate to the project directory first).
  398. ```bash
  399. sbx exec -it <sandbox-name> bash
  400. cd /path/to/your/project # this is the same path as the path in the root machine, e.g. /Users/your-username/Documents/your-project
  401. claude # or codex, copilot, cursor, gemini, opencode
  402. ```
  403. Re-running `./ralph.sh`, `./ralph.sh --login`, or `./ralph.sh --ports` is safe at any point — Ralph probes `sbx ls` and emits `sbx run --name ... <agent> .` only when the sandbox doesn't exist yet, and `sbx run <sandbox-name>` to reattach afterwards. The first form is create-only and would otherwise error with `--name can only be used when creating a new sandbox`. See [RALPH.md](RALPH.md#create-vs-attach-lifecycle) for the full lifecycle.
  404. ### Allowing network access
  405. Docker Sandboxes block outbound HTTP/HTTPS by default (deny-by-default, or a "Balanced" allowlist depending on the policy you chose at install). If the agent can't reach a host it needs — `npm install` fails, an API call is refused, package downloads hang — grant access with `sbx policy`. Changes take effect immediately and persist across sandbox restarts.
  406. Use the sandbox name from `sbx ls` (or `./ralph.sh --print-name`), e.g. `ralph-claude-my-app-a1b2c3d4`.
  407. Allow a single domain for one sandbox:
  408. ```bash
  409. sbx policy allow network <my-sandbox> api.example.com
  410. ```
  411. Allow all outbound traffic for one sandbox (use sparingly — this opts that sandbox out of network filtering):
  412. ```bash
  413. sbx policy allow network <my-sandbox> "**"
  414. ```
  415. Allow several domains at once with a comma-separated list (handy when package installs are blocked):
  416. ```bash
  417. sbx policy allow network <my-sandbox> "*.npmjs.org,*.pypi.org,files.pythonhosted.org,github.com"
  418. ```
  419. Apply a rule to every sandbox on the machine with the global flag `-g` instead of a sandbox name:
  420. ```bash
  421. sbx policy allow network -g api.example.com
  422. ```
  423. Inspect and manage rules:
  424. ```bash
  425. sbx policy ls # list active rules
  426. sbx policy log # inspect connection history
  427. sbx policy deny network <my-sandbox> ads.example.com # block a host
  428. ```
  429. Domain matching notes:
  430. - `example.com` matches only the exact domain (any port); it does **not** match subdomains.
  431. - `*.example.com` matches subdomains like `api.example.com` but **not** the root `example.com` — specify both to cover both.
  432. - Append a port to scope the rule, e.g. `example.com:443`.
  433. - If a domain matches both an allow and a deny rule, the deny rule wins.
  434. See Docker's [Policies](https://docs.docker.com/ai/sandboxes/security/policy/) and [Network policies](https://docs.docker.com/ai/sandboxes/network-policies/) docs for the full reference.
  435. ### Authentication issues in Sandboxes / Login not persisting
  436. Agentic CLIs might change their auth mechanism over time and Docker Sandboxes might fail persisting OAuth tokens (when you perform `/login` inside the sandbox shell).
  437. Fortunately, Docker Sandboxes also forward env variables **when you create a sandbox**.
  438. Here's how to set up authentication using an API key:
  439. 1. Important 🚨: delete the sandbox that needs authentication. Env vars are only picked up when you create a new sandbox.
  440. 2. Go to [Docker security credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) to find each env variables you need. For example, anthropic needs `ANTHROPIC_API_KEY`, OpenAI need `OPENAI_API_KEY`, Cursor needs `CURSOR_API_KEY`, etc.
  441. 3. Export the env variables in your shell. For example:
  442. ```bash
  443. export ANTHROPIC_API_KEY=your-anthropic-api-key
  444. export OPENAI_API_KEY=your-openai-api-key
  445. export CURSOR_API_KEY=your-cursor-api-key
  446. ```
  447. > If you use bash, you can export the env variables in your `.bashrc` file, or if you use zsh, you can export the env variables in your `.zshrc` file.
  448. 4. Recreate the sandbox by running `./ralph.sh --login` again.
  449. ## License
  450. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.