Developer Setup¶
Openbase is designed for founders, contractors, and small-company developers who need their coding environment available on the go. The GitHub repository is the developer entry point; the setup script below owns the installation.
Installing from the GitHub workspace is the strongly recommended, fully
supported install path, with
an interactive terminal flow: run ./scripts/setup with no flags and it
picks your coding backend and voice audio provider, walks you through
Openbase Cloud login, and verifies the install. Use it when you want to
develop Openbase Coder itself, run the runtime from source, or set up a
machine without the desktop app (for example a headless Linux box you
administer over SSH). (Just want the product on a Mac? See
Mac App Download. On Windows, ./scripts/setup runs natively in
beta — or use the Docker image, the most battle-tested Windows
option today.)
Prerequisites¶
In addition to the shared prerequisites, development installs need:
- On macOS, Homebrew, which the
brew installcommands below use - Git:
xcode-select --installon macOS, or your distribution's package on Linux (for examplesudo apt install git) uv:curl -LsSf https://astral.sh/uv/install.sh | shmulti3.2.21 or newer, which setup uses to sync the sub-repos:uv tool install multi-workspace && uv tool update-shell, then open a new terminal (oruv tool upgrade multi-workspaceto update it)- Go:
brew install goon macOS, or the current toolchain from go.dev/dl. Setup builds the Openbase Direct transport from source, so Go is required whichever transport you pick. - Node, the LTS version pinned in the workspace's
.nvmrc(currently Node 24), installed with nvm as described under Node below, and pnpm (curl -fsSL https://get.pnpm.io/install.sh | sh -) for building the console from source
./scripts/setup checks for all of these before it does anything else and exits with the install command for each one that is missing.
If pnpm --version already works (for example from npm install -g pnpm or Corepack), keep that pnpm and skip installing another. A second copy only conflicts: brew install pnpm then stops with a link error because pnpm already exists in the Homebrew bin directory. That error is harmless, since setup uses whichever pnpm is on your PATH; to switch to the Homebrew copy instead, run brew link --overwrite pnpm.
uv tool update-shell adds ~/.local/bin, where uv installs multi, to your shell's PATH; a fresh Mac does not have it. Without it, setup reports multi as missing even though it is installed. In a terminal that is already open, export PATH="$HOME/.local/bin:$PATH" does the same for that session.
Contributors who commit to the repos also need gitleaks (brew install gitleaks). Setup does not need it, but the git hooks that multi sync installs refuse commits and pushes without it.
Optional developer backends:
- Codex CLI (
npm install -g @openai/codex) for thecodexbackend - Claude Code (
curl -fsSL https://claude.ai/install.sh | bash) for theclaude-codebackend
Openbase uses your own Codex or Claude Code login. If the backend you pick in setup isn't signed in yet, interactive setup says so and offers to sign you in (codex login or claude login). Otherwise sign in yourself before your first call; openbase-coder claude login is a thin wrapper around claude login.
Node¶
The workspace pins one tested Node LTS in .nvmrc, and setup refuses any other major version: newer Node releases are not drop-in (Node 26 breaks Electron's install). Install it with nvm rather than brew install node, which tracks the newest release. On a fresh Mac, zsh has no ~/.zshrc yet, so create it first or the nvm installer cannot add its loader:
Then open a new terminal (or run source ~/.nvm/nvm.sh) so the nvm command exists. The clone step below runs nvm install and nvm use in the workspace, which read .nvmrc. The first version nvm installs becomes its default for new terminals; if your nvm default is another version, run nvm use in the workspace before each ./scripts/setup. Setup prints these commands and stops when node is the wrong major. If an older brew install node is still installed, nvm's Node takes precedence once nvm is loaded.
Clone and Run Setup¶
Clone the workspace repo and run its setup script from the workspace root.
It syncs the sub-repos with multi, builds the console from source, and
runs openbase-coder setup against your checkout:
git clone --branch main --single-branch \
https://github.com/openbase-community/openbase-coder-workspace
cd openbase-coder-workspace
nvm install && nvm use # the Node pinned in .nvmrc
./scripts/setup
With no flags, setup runs interactively on a fresh install: numbered pickers
choose the coding backend (codex, claude-code, or openbase-cloud) and
the voice audio provider — Cloud TTS/STT (the recommended default),
bring-your-own-keys (AssemblyAI + Cartesia; setup prompts for the keys), or
local models (not recommended; see Local-Only Mode).
Passing any flag disables all prompts, so scripted and AI-agent runs
never block: fresh non-interactive installs require --backend and default
the audio provider to openbase-cloud. See setup
for the full flag list and the --interactive override.
Interactive runs offer openbase-coder login (browser OAuth), then confirm the device is registered with Openbase Cloud and that the selected private-network transport exposes the local API and LiveKit. Non-interactive runs print the login hint instead. Either way, ./scripts/setup then builds and launches the developer app (see below), prints "Setup complete" and a short summary of what setup changed on your machine, and finishes with a QR code for the phone app downloads page: install the iOS or Android app last.
If a standalone desktop/CLI install, or a different development workspace
install, already exists, the workspace script stops and links to
Uninstall. Uninstall first, then rerun ./scripts/setup.
Setup never clones or git-updates a workspace itself. When run without
--workspace-dir (and no bundled runtime package is present), it discovers
the workspace from the one recorded in ~/.openbase/installation.json, then
from the checkout behind an editable CLI install; otherwise it errors and asks
you to clone the workspace or use the standalone install.
Visual developer apps¶
On macOS, ./scripts/setup always builds the Electron developer app: it
installs and verifies the Electron runtime, builds the dashboard renderer, and
installs the Openbase launcher in /Applications. Setup fails, rather than
reporting success, if any of those steps fails. In a logged-in desktop session, setup then launches the app together with the Swift menu-bar UI automatically. Over SSH, with OPENBASE_SETUP_NO_LAUNCH=1, or when a packaged Openbase app already occupies /Applications, it only builds them. You can launch either later:
./scripts/dev-launch --electron # dashboard/status only; setup is disabled
./scripts/dev-launch --menu-bar # native Swift Openbase networking status UI
./scripts/dev-launch --all # both
The Electron developer launch requires the desktop checkout (part of the
default install set; run multi sync to fetch it). Its closed-source netmesh
companion is fetched as a prebuilt signed artifact during the desktop build,
so the open desktop sources build without it. It sets an explicit
dashboard-only mode, and Electron also detects the development installation in
installation.json; either way, it does not expose the installer bridge.
Never use the Electron onboarding wizard for a development install:
./scripts/setup is the only setup authority.
The same launchers are available as VS Code tasks. React/Electron runs from
tasks.json; the Swift UI is built with Xcode tools and opened as a menu-bar
app.
After Setup¶
Interactive setup already signs you in to Openbase Cloud. If you skipped that step, or ran setup with flags, sign in now (required for phone app pairing and cloud onboarding):
Then verify the install with the health check commands.
Start the Server¶
Setup installs background services that run the server for you. To run it in the foreground instead — for example while developing:
By default this command:
- Runs Django migrations
- Runs
collectstatic - Rebuilds the console in development mode
- Starts Gunicorn + Uvicorn worker(s)
Next Steps¶
Continue with the next steps on the Getting Started
overview. For the developer install/test workflow, contribution branches, and
service debugging, see the workspace repo's DEV_RUNBOOK.md.