1+ ---
2+ description : How to install, launch, and use the ralphify web dashboard to manage runs, browse prompts, edit primitives, and review history.
3+ ---
4+
15# Web Dashboard
26
37Ralphify includes a web-based orchestration dashboard that lets you manage
@@ -8,16 +12,24 @@ your browser.
812
913The dashboard requires optional dependencies:
1014
11- === "uv"
15+ === "uv tool (recommended)"
16+
17+ If you installed ralphify with `uv tool install`, reinstall with the UI extra:
18+
19+ ```bash
20+ uv tool install "ralphify[ui]"
21+ ```
22+
23+ === "pipx"
1224
1325 ```bash
14- uv pip install ralphify[ui]
26+ pipx install " ralphify[ui]"
1527 ```
1628
1729=== "pip"
1830
1931 ```bash
20- pip install ralphify[ui]
32+ pip install " ralphify[ui]"
2133 ```
2234
2335This adds FastAPI, uvicorn, and WebSocket support.
@@ -41,52 +53,67 @@ To expose the dashboard on your network:
4153ralph ui --host 0.0.0.0 --port 9000
4254```
4355
44- ## What you can do
56+ ## Dashboard tabs
4557
46- ### Start and manage runs
58+ The dashboard has four tabs. ** Prompts ** is the default landing page.
4759
48- Click ** New Run ** in the sidebar to start an autonomous loop. The modal lets you:
60+ ### Prompts
4961
50- - ** Pick a named prompt** — cards show every prompt discovered in ` .ralph/prompts/ `
51- - ** Enter an ad-hoc prompt** — type a one-off task without creating a file
52- - ** Configure settings** — max iterations, delay between iterations, timeout, and stop-on-error
62+ The Prompts tab shows every named prompt discovered in ` .ralph/prompts/ ` as a
63+ card grid. Each card displays:
64+
65+ - ** Name** and ** description** (from the prompt's frontmatter)
66+ - A ** content preview** of the prompt body
67+ - An ** Edit** button that opens an inline editor
68+ - A ** Run** button that opens the New Run modal with that prompt pre-selected
5369
54- Once a run starts, you can ** pause** , ** resume** , or ** stop** it from the sidebar or the run view.
70+ Use this tab to quickly browse your prompts, start a run from a specific one,
71+ or create new prompts without leaving the browser.
5572
56- ### Watch iterations live
73+ ### Timeline
5774
58- The ** Timeline ** tab shows each iteration as it completes :
75+ Select a run in the sidebar to see its iterations as they complete :
5976
6077- Pass/fail status with color-coded badges
6178- Agent output (truncated to 5,000 characters, same as the CLI)
6279- Check results with individual pass/fail/timeout indicators
6380- Duration and return codes
6481
65- Events stream over WebSocket, so the page updates without refreshing.
66-
67- ### Track check health
82+ Each check gets a ** sparkline bar ** showing its pass/fail history across
83+ iterations. Green means pass, red means fail, yellow means timeout — useful for
84+ spotting flaky checks or regressions at a glance.
6885
69- Each check gets a sparkline bar showing its pass/fail history across iterations.
70- Green means pass, red means fail, yellow means timeout. This makes it easy to
71- spot flaky checks or regressions at a glance.
86+ Events stream over WebSocket, so the page updates without refreshing.
7287
73- ### Browse and edit primitives
88+ ### Configure
7489
75- The ** Primitives ** tab lists all checks, contexts, instructions, and prompts in
76- your project. You can:
90+ The Configure tab lists all checks, contexts, and instructions in your project.
91+ You can:
7792
7893- View the frontmatter and body of each primitive
94+ - Toggle primitives on and off with enable/disable badges
7995- Create new primitives
8096- Edit existing ones
8197- Delete primitives you no longer need
8298
8399Changes are written directly to the ` .ralph/ ` directory on disk.
84100
85- ### Review run history
101+ ### History
102+
103+ Shows all past runs organized by status — completed, stopped, and failed. Each
104+ run displays its pass rate and iteration count. Click any run to jump to the
105+ Timeline view and see its full iteration details.
106+
107+ ## Starting a run
108+
109+ Click ** New Run** in the sidebar to open the run modal. It lets you:
110+
111+ - ** Pick a named prompt** — cards show every prompt discovered in ` .ralph/prompts/ `
112+ - ** Enter an ad-hoc prompt** — toggle to ad-hoc mode and type a one-off task
113+ - ** Configure settings** — expand the settings panel to set max iterations, delay between iterations, timeout, and stop-on-error
86114
87- The ** History** tab shows all past runs organized by status — completed,
88- stopped, and failed. Click any run to see its full iteration timeline and
89- check results.
115+ Once a run starts, you can ** pause** , ** resume** , or ** stop** it from the
116+ sidebar or the controls bar above the Timeline.
90117
91118## Architecture
92119
0 commit comments