Getting Started

(Optional) Set up code base

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

npx @tanstack/cli create lib --add-ons eslint,form,tanstack-query,nitro --no-git

If you must start from a blank slate, which is not recommended, see 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

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

Use the prd-creator skill to generate a PRD from your requirements.
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 for a more realistic example on how to write requirements.

✨ Pro tips

• 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

Then, follow the Skill’s instructions and verify the PRD and then tasks.
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 and Docker Sandboxes docs 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.

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 for per-agent setup details.

If you want to use a different agentic CLI, see Running with a different agentic CLI.

4️⃣ Step 4: Run Ralph

./ralph.sh -n 50 # Run Ralph Loop with 50 iterations

✍️ Note: the first iteration will be spent on ensuring the named sandbox environment is set up correctly. Expect 5 minutes to complete.