Installation Guide

1. Installing

1.1 Global npm package

Run the following command:

• Works on macOS, Linux, and Windows (Node.js 18 LTS or newer required)
• The CLI stub it installs simply launches the GUI

2. First launch

• Type localforge in any terminal, from any directory

3. Initial configuration

First things first, you need to open Settings by clicking the gear icon in the top-right corner and set up at least one provider. The window has three tabs:

• Models
• Web Integration

Complete the steps below in order.

3.1 Models tab – adding providers

"Available Provider Types" shows the integrations currently supported (note that most if it is just v1 openai api, just different url):

Under "Your Provider List" click Add, pick a provider, and enter its API key if required:

• OpenAI – create a secret key at https://platform.openai.com/account/api-keys
• Gemini – create a key at https://aistudio.google.com/app/apikey
• Anthropic – create a key in the Anthropic console
• VertexAI – enable the Vertex AI API in Google Cloud and create a service account key
• LocalOllama – no key needed; Localforge connects to your running Ollama daemon

You can rename, edit, or delete any provider later with the pencil and trash icons. All keys are stored only in $HOME/.localforge/db/* (Unix) or %APPDATA%\Localforge\db\* (Windows) and never transmitted elsewhere.

3.2 Models tab – choosing LLMs

At the bottom of the Models tab you'll find the three-slot pipeline:

• Aux Model – lightweight tasks and metadata
• Main Model – primary chat interaction
• Expert Model – heavy refactors or complex reasoning

For each slot first choose the provider in the upper drop-down, then select the exact model name below it. Changes take effect immediately. Recommended defaults:

Slot	Provider	Model	Purpose
Aux Model	OpenAI	gpt-4.1-mini	Lightweight tasks and metadata
Main Model	OpenAI or Anthropic	gpt-4.1 or claude-3-7-sonnet-20250219	Primary chat interaction
Expert Model	Gemini or OpenAI	gemini-2.5-pro-exp-03-25 or o3	Heavy refactors or complex reasoning

3.3 Web Integration tab

Web Search Integration (Optional - Expand to Configure)

This section is only needed if you want your agent to search the web. You can set it up later.

• Headless Browser – toggle the built-in Chromium instance. Keep it on for sites that block plain HTTP fetches (e.g., Reddit); turn it off to save RAM.
• Google Search – optional but useful for in-context web results.

Google Search setup:

You'll need two things:

• 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

Quota notes:

• Google provides about 100 free queries per day
• For sustained use, add billing and set quotas in Google Cloud if you need more

---

3.4 Saving settings

Press "Save Changes" on any tab to write the configuration. Localforge reloads its agent stack instantly with the new providers and model choices.

You are now ready to start a session: type your prompt in the main window and watch Localforge coordinate the Aux, Main, and Expert models to get the job done—entirely on your own hardware.

Note: If some settings don't appear to apply correctly, try restarting the app after making changes.

Last updated 22 Apr 2025