Installation
Riverforge ships as a single Windows installer plus a VS Code extension. The installer sets up Ollama, pulls a model, configures the environment and drops two desktop apps. This page covers the requirements, the install itself, and how to confirm it all works.
Private beta. Riverforge is not publicly released yet — the packaged Windows installer lands on the website soon. The steps below describe how it installs and sets itself up.
Requirements
Riverforge was designed low-end first. It is genuinely useful on a modest machine, and it scales straight up if you have more.
Minimum
| Requirement | Minimum |
|---|---|
| OS | Windows 10 / 11, 64-bit |
| RAM | 16 GB |
| GPU | NVIDIA GPU with 8 GB VRAM — or CPU-only if you accept much slower responses |
| Disk | 40–80 GB free for models, dependencies, data and logs |
| VS Code | 1.90 or newer |
| Ollama | Installed locally on http://127.0.0.1:11434 (the installer can do this for you) |
Recommended
| Requirement | Recommended |
|---|---|
| RAM | 32 GB or more |
| GPU | RTX 3070 (8 GB VRAM) or better |
| Disk | 100 GB free, on an SSD/NVMe |
| Models | A chat model that fits your GPU (see Choosing your model) plus mxbai-embed-large for embeddings |
| Data folder | A stable folder outside temporary downloads, e.g. D:\RiverforgeData |
Below the recommended spec everything still works — model loading and long responses are just slower. Riverforge runs well on a modest 8 GB card, and scales straight up: give it more VRAM and you can run a larger, more capable model.
Install with the Windows installer
This is the normal path. You do not need Python, Node, or any command line for day-to-day use once the installer and extension are in place.
- Get the installer. Download
RiverforgeSetup-<version>.exeand run it. It’s published by Aurasoft UK. - Choose the install folder. Keep the default unless you have a reason not to. New installs go under
Program Files; upgrades preserve your previous install directory. - Pick a model storage folder. If
OLLAMA_MODELSis not already configured, you’ll be asked where to store models. Choose a drive with plenty of free space — models are several gigabytes each. - Choose your chat model. The installer offers a few benchmarked models — pick the one that suits your GPU (see Choosing your model below). Gemma 4 Turbo is pre-selected as a fast default for ~8 GB cards, and you can download more than one to switch between. It always also installs
mxbai-embed-largefor embeddings. - Let setup do the heavy lifting. It detects or installs Ollama (via
winget), startsollama serveif needed, sets the Ollama tuning environment variables, pulls any missing models, and tries to install the bundled VS Code extension. - Keep the desktop shortcuts. Leave the options enabled to get quick access to the Riverforge Tray and Riverforge Memory Visualizer.
- Finish. On the last page, choose whether the tray should start at Windows login, and whether to restart now so other apps pick up the new environment variables.
What the installer configures
| Area | Behaviour |
|---|---|
| Install location | Program Files by default; upgrades keep the previous directory |
| Shortcuts | Start Menu entries plus desktop shortcuts for the tray and the visualiser |
| Ollama | Detects, installs with winget if missing, and starts ollama serve when the API isn’t already up |
| Models | One required chat model, always mxbai-embed-large, plus optional extras |
| Environment | Sets the Ollama tuning vars (context length, max loaded models, keep-alive) under your user scope |
| VS Code extension | Bundles the VSIX and tries code --install-extension when the CLI is on PATH |
| Autostart | Optional scheduled task that launches the tray silently at logon |
| Data folder | Defaults to %APPDATA%\Riverforge unless you choose another location |
| Uninstall | Removes binaries and the autostart task, but leaves your data and models in place |
Choosing your model
Riverforge runs any local model — the installer just offers a few that have been benchmarked so you don’t have to guess. The right one depends on your GPU. Bigger models are more capable but need more VRAM and answer more slowly.
| Model | Good for |
|---|---|
| Gemma 4 Turbo (4B) | The fast pick for ~8 GB-VRAM cards. Pre-selected because it’s quick on modest hardware — speed is the trade-off, not the ceiling. |
| Gemma 4 (e4b) | The standard small Gemma 4 — a little more considered than Turbo on the same class of card. |
| Qwen 3.5 9B | A strong all-rounder if your card can run it — more capable than Turbo, in exchange for more VRAM and time. |
| Qwen 2.5 Coder 14B | A larger, coding-focused model for higher-VRAM machines. |
| Gemma 4 26B | The most capable option — best on high-VRAM systems. |
Gemma 4 Turbo is the default only because it’s fast on an 8 GB GPU like the one Riverforge is tuned around — it isn’t “the best” model. If you have the VRAM, Qwen 3.5 9B or Gemma 4 26B will be noticeably more capable. You can install more than one and switch any time from the Models panel — see Models & Hardware.
Install the VS Code extension
The installer bundles the extension and usually installs it automatically. If the Riverforge activity-bar icon isn’t there afterwards, install it by hand — it takes ten seconds.
- Open VS Code and go to the Extensions view (Ctrl+Shift+X).
- Click the … menu at the top of the Extensions view.
- Choose Install from VSIX…
- Pick the bundled
riverforge-vscode.vsixfrom your Riverforge install folder. - Reload VS Code if prompted, then open the Command Palette (Ctrl+Shift+P) and run Riverforge: Open Chat.
The VS Code CLI can install into a different VS Code profile than the one you’re using. If the chat panel still looks missing after an upgrade, install the bundled VSIX manually into the exact window you work in, then reload. See the VS Code Extension page for the full tour.
Verify the install
Two quick checks confirm everything is talking to everything else.
- Launch the Riverforge Tray from the desktop shortcut and click Start Server. Wait for the status log to say the server is online.
- In VS Code, run Open Chat and look at the header dot: green means the server is reachable. Send “What is this workspace?” to confirm the model responds.
Prefer the command line? With the server running, these should both return cleanly:
PS> Invoke-RestMethod http://127.0.0.1:8765/health
PS> (Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8765/ready).StatusCode # 200The server runs locally at http://127.0.0.1:8765. If you ever need to point the extension elsewhere, it’s the riverforge.serverUrl setting — see the VS Code Extension page.
Updating
- Run the new
RiverforgeSetup-<version>.exeover your existing install. - Let setup re-run so Ollama, environment variables, model pulls and the bundled extension all stay aligned with the new build.
- Restart Windows if the installer recommends it after changing environment settings.
- If the VS Code commands still look old, reinstall the bundled VSIX and reload VS Code.
Your data folder and models are never touched by an upgrade or uninstall — see Data & Backup for what lives where.