← Product overview

Ralpha Brain

Getting started with the Ralpha Brain

What the Brain is

The Ralpha Brain is an app that builds a scene in your open Unreal project from a text prompt or a reference image, then improves it over several iterations. It plans each change and scores each frame with Claude, through your own Claude Code sign-in.

The Ralpha Brain is free during early release. If we introduce paid plans later, we'll announce it at least 30 days in advance, and the version you've downloaded will keep working.

Requirements

  • Unreal Engine 5.8 with the Ralpha plugin from Fab (free for individuals), enabled in the project you want to build in. The Brain needs plugin 1.2.0 or later. See the plugin page to install it.
  • Claude Code, installed and signed in. The Brain runs on your own Claude subscription; it does not include a model or an account of its own.
  • A Mac with Apple silicon, or a Windows 64-bit PC. There is no Linux build of the Brain.

Download and unzip

Download the zip for your computer from the download page. Each is just under 1 GB. Unzip it anywhere; inside is the ralpha-brain program (ralpha-brain.exe on Windows).

Download for Win64Download for Mac (Apple silicon)

The Windows build is not code-signed yet, so Windows may warn about an unknown publisher. Choose More info, then Run anyway.

Mac

The Mac build is signed and notarized by Apple. Double-click the zip in Finder to unzip it.

Windows

The Windows build is not code-signed yet, so Windows does not know who published it and may warn you. What you see depends on your settings:

  • Your browser may say the zip isn’t commonly downloaded. Choose to keep the file.
  • When the program first runs, Microsoft Defender SmartScreen may show “Windows protected your PC” with the publisher as unknown. Select More info, then Run anyway.

To clear the warning for every file at once, right-click the zip before you unzip it, choose Properties, tick Unblock and select OK.

Set up

Open Terminal (Mac) or PowerShell (Windows) in the unzipped folder and run setup:

./ralpha-brain setup
.\ralpha-brain.exe setup

Setup does two things:

  1. It installs the Brain into ~/.ralpha (on Windows, .ralpha in your user folder), where ralpha-brain update keeps it current.
  2. It configures Claude Code, Claude Desktop and Cursor. In Claude Code it registers two servers for your user: unreal, which is Unreal’s own MCP server at http://127.0.0.1:30030/mcp, and ralpha, which is the Brain. It never replaces an unreal entry you made yourself. If Claude Code is not signed in, it says so.

Restart Claude Code, Claude Desktop or Cursor afterwards so it picks up the change. Useful options:

  • --client claude-code configures Claude Code only.
  • --dry-run prints what setup would change without changing it.
  • --native-port sets the port of Unreal’s MCP server, if you use one other than 30030.

From now on, run the installed copy: ~/.ralpha/current/ralpha-brain on a Mac, or ~\.ralpha\cache\v1.3.1\ralpha-brain.exe in PowerShell on Windows. The rest of this page writes it as ralpha-brain.

Check with doctor

Open your project in Unreal first, then run:

ralpha-brain doctor

Doctor checks the Brain’s install, Unreal’s MCP server on port 30030, the Ralpha plugin on TCP port 30010 and its version, and Claude Code: that it is installed, signed in, and has the unreal and ralpha servers. Its checks only read, and change nothing in the editor. A healthy result ends with All checks passed:

Ralpha Brain — Doctor
  Brain version         ralpha-brain 1.3.1 (build …)
  RALPHA_HOME           /Users/you/.ralpha
  …
  Unreal MCP @ 30030    reachable on http://127.0.0.1:30030/mcp
  Ralpha TCP @ 30010    reachable on 127.0.0.1:30010
  Plugin version        v1.3.2  (this brain requires >= v1.2.0)
  Claude Code           …  (/usr/local/bin/claude)
  Claude Code login     signed in (…)
  Claude Code 'unreal'  http://127.0.0.1:30030/mcp
  Claude Code 'ralpha'  /Users/you/.ralpha/current/ralpha-brain

All checks passed.

When a check fails, doctor ends with a numbered list of next steps instead. The usual ones:

Unreal MCP @ 30030: NOT reachable
Unreal’s own MCP server is off. Enable the Model Context Protocol plugin in your project, then in Editor Preferences → Model Context Protocol tick Auto Start Server and set the port to 30030. Claude Code’s unreal server needs this; the Brain’s own runs use the plugin’s TCP port and work without it.
Unreal MCP: “not an HTTP MCP endpoint” or “Ralpha’s direct HTTP endpoint”
Something else is on that port. If you moved Unreal’s MCP server, pass its port: ralpha-brain doctor --native-port 8000.
Ralpha TCP @ 30010: NOT reachable
Open your project in UE 5.8 with the Ralpha plugin enabled, wait for the editor to finish loading, and run doctor again.
Plugin version: “doesn’t expose version”
The plugin is probably older than this Brain supports. Update it from your Fab library.
Claude Code: NOT installed
Install Claude Code, sign in, then run ralpha-brain setup --client claude-code.
Claude Code login: NOT signed in
Run claude auth login, or start claude once and sign in.
Claude Code 'unreal' or 'ralpha': not registered, or MISSING on disk
Run ralpha-brain setup --client claude-code.

Your first run

The Brain builds in a new level in the project you have open, so save your work first and use a project you are happy for it to change. Describe a scene:

ralpha-brain --prompt "a calm mountain lake at sunset" --llm claude-code --max-iterations 3

Or give it a photo to match:

ralpha-brain --reference image.jpg --llm claude-code --max-iterations 3

Always pass --llm claude-code: it is what makes the Brain use your Claude Code sign-in. Without --max-iterations a run can go on for up to 50 iterations by default, so set a small number for a first try.

What you see

  1. A pre-flight check. If it cannot reach the editor, it stops and says so.
  2. The Brain reads your prompt or image and lists what the scene contains. This takes a couple of minutes.
  3. It creates a new level and builds the scene in the editor: sky, sun, light, and the elements your project has assets for. You can watch it in the viewport.
  4. Each iteration plans changes, makes them, captures a frame and scores it. An iteration takes about 12–15 minutes, so a three-iteration run takes around 45 minutes.

The terminal prints each step as it goes. Add --dashboard to follow the run in a browser page served from your own machine.

The Brain uses only what your project contains. In a new, empty project there are no terrain, plant or prop assets, so most scenes come out as sky, light and water; the run records each element it had no asset for.

Update

ralpha-brain update --check-only
ralpha-brain update

--check-only tells you whether a newer Brain is out. Without it, update downloads the new version, keeps the old one, and switches to the new one. To go back, run ralpha-brain rollback.

update also prints a check for the plugin. Plugin updates come from your Fab library.

Where runs are saved

Each run gets its own folder under ~/.ralpha/sessions/runs/ (on Windows, .ralpha\sessions\runs in your user folder), named for the date and time it started. The terminal prints the folder as Session directory when the run begins. Inside:

  • result/best.png: the best-scoring frame, and result/metadata.json with its score.
  • screenshots/: the frame from every iteration.
  • history/: what each iteration changed.

At the end of a run the Brain tries to put the editor back on the best scene. If that fails, it reports RESTORE_FAILED and the editor stays on a later scene; result/best.png is still the best frame.

Getting help

Ask in the forum thread linked from the Ralpha listing on Fab. Include the output of ralpha-brain doctor; it shows your versions, ports and paths, and never prints your Claude account’s email.

Version notes: Brain 1.3.1 · support@ralpha.io