Installation Guide

1. Installing

1.1 macOS DMG

• Download the signed DMG installer (download here)
• Double-click to mount, then drag the Localforge icon into Applications
• Eject the disk image. The GUI now appears in Launchpad and via Spotlight exactly like any other app

1.2 Global npm package

• Copy-paste the following command: npm install -g @rockbite/localforge
• Works on macOS, Linux, and Windows (Node.js 18 LTS or newer required)
• The CLI stub it installs simply launches the GUI

1.3 Run from source

• Clone the repository (GitHub repository)
• From the repo root run npm ci to install dependencies
• Start the application with npm run start
• This route is aimed at contributors who need bleeding-edge code

2. First launch

• DMG: open Applications and double-click Localforge
• npm: type localforge in any terminal, from any directory

A first-run dialog appears if no settings file exists.

3. Initial configuration

Settings button is in the top-right corner

3.1 OpenAI API key

Required for every language or code task.

How to obtain:

1. Open https://platform.openai.com/account/api-keys in a browser
2. Click "Create new secret key"
3. Copy the generated string. The popup never shows it again, so store it in a password manager
4. Paste the key into the OpenAI field inside Settings
5. Press "Save". Localforge writes the key only to $HOME/.localforge/config.json (Unix) or %APPDATA%\Localforge\config.json (Windows) and never transmits it anywhere else

Note: Gemini and Claude keys will appear in this same panel once their adapters ship.

3.2 Models choice

Slot	Current Model	Purpose
Slot 1 "helper"	gpt-4o-mini	Speedy metadata work
Slot 2 "main chat"	gpt-4o	Primary interaction
Slot 3 "expert"	o3	Heavy refactors

These fields are disabled for now; they will become editable soon.

3.3 Web integration

• Toggles a headless Puppeteer instance that piggybacks on the user's local Chrome install
• Enabled by default because many hostile sites (for example Reddit) require a full browser
• Disabling saves a few hundred MB of RAM but means some pages may refuse to load

3.4 Google Search credentials

Optional but strongly recommended for improved search capabilities.

What you need:

• Google API Key
• Google Custom Search Engine (CSE) ID

Exact steps to generate the API Key:

1. Sign in at https://console.cloud.google.com/ (Google account required)
2. Click the project dropdown in the top bar and choose "New Project". Name it "Localforge-CSE" (any name is fine) and press "Create"
3. With the new project selected, open the left-hand navigation menu ▸ APIs & Services ▸ Library
4. Search for "Custom Search JSON API", click the card, then press "Enable"
5. After enabling, the page redirects to the API overview. Click "Credentials" in the sidebar
6. Press "Create credentials" ▸ "API key"
7. Copy the key that appears in the modal. Keep that tab open in case you want to restrict IPs later
8. Paste the key into the "Google API Key" field in Localforge Settings

Exact steps to generate the CSE ID:

1. In a new browser tab open https://cse.google.com/cse/create/new
2. Under "Sites to search" enter an asterisk * (this tells Google to search the entire web)
3. Name the search engine something like "Localforge Universal Search"
4. Click "Create"
5. On the confirmation screen click "Control Panel"
6. In the Basics section toggle "Search the entire web" ON if it is not already
7. Scroll to "Search engine ID". Copy the long string that starts with "###########:"
8. Paste this string into the "Google CSE ID" field in Localforge Settings
9. Press "Save"

Quota notes:

• Google gives roughly 100 free queries per day
• For sustained use you must add a billing account in Google Cloud Console ▸ Billing and set daily caps
• Localforge never exceeds one query per user action, but running autonomous tasks can eat quota quickly, so monitor it

---

After saving, Localforge reloads the agent with the new credentials.

Last updated 22 Apr 2025