Docs
Back to site
openFoundry
Run locallyDownload

Setup

Two ways to run openFoundry, one workspace. Install the macOS app or start the web server, claim the install, then sign in.

What you need

  • macOS 13.5 or later on Apple silicon for the desktop app.
  • Node.js 20.9 or later for the web workspace.
  • No account, no cloud subscription and no usage bill.

Both routes open the same workspace. The desktop app adds a native window and a bundled Node runtime. The web route runs the same server in your own terminal.

macOS desktop

  1. Download the current DMG from the releases page.
  2. Open the DMG and drag openFoundry to Applications.
  3. The build is ad-hoc signed and not notarized. The first time, right-click the app and choose Open, then confirm. On macOS 15 and later, use System Settings, Privacy and Security, Open Anyway.
  4. The welcome step lists the terms. Accept them and continue. The profile step asks for a display name, initials and an email.
  5. Point the provider step at Foundry Local, Ollama, LM Studio or llama.cpp, then pick a model.
The desktop shell holds a machine credential in the app data folder and signs the local user in. You can issue an access code for another browser later, on the Access control page.
The first run wizard with the welcome step, terms and the five step rail.
The first run wizard: terms, profile, providers, model, ready.
The profile step with display name, initials and email fields.
The profile step. The web build also asks for the setup token here.

Web workspace

Clone the repository and install the dependencies. Use Node.js 20.9 or later.

git clone https://github.com/Sharjeelbaig/openFoundry.git
cd openFoundry
npm install
npm run dev

The first start prints a one-time setup token to the terminal and opens the setup screen. Enter the token with your name and email. The app creates the owner and shows an access code once.

The first browser to reach an unclaimed install cannot become the owner without the token printed by the server. That is what stops a takeover when the port is exposed.

Open http://localhost:3000. If the token expired, restart the server. It prints a fresh one while the install has no owner.

Windows

The desktop build for Windows is not available yet. The web workspace runs on Windows with Node.js 20.9 or later, using the same commands as above.

The packaged app is macOS only for now. Windows packaging is tracked in issue 1.

After setup

Sign in at /signin with your access code. On a web install the code is the only credential. Lose it and run this from the project folder:

npm run access-code

It prints a new code for the owner and revokes the old one. It needs the same filesystem access the server already has, so it is not a remote reset.