local-dev-environment

Local Development Environment Setup (macOS)

Complete guide for setting up the Brainforge engineering CLI toolchain on macOS. This covers all tools needed for Platform development, OpenWork, data pipelines, and day-to-day engineering workflows.

---

Quick Start

If you already have Homebrew installed, you have two options:

Option 1: Quickstart script (recommended)

Run the automated installer from the repo root:

./scripts/quickstart-install.sh

Option 2: Manual one-liner

If you prefer to install manually, run this one-liner to install everything:

# Install Homebrew first if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 
# Install all core tools
brew install git gh fzf jq ripgrep fd eza zoxide delta atuin lazygit ngrok wget
brew install --cask 1password-cli
 
# Install nvm and Node 22
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install 22 && nvm use 22 && nvm alias default 22
 
# Install global Node packages
npm install -g pnpm @googleworkspace/cli
 
# Install Bun
curl -fsSL https://bun.sh/install | bash
 
# Install OpenCode CLI
curl -fsSL https://opencode.ai/install | sh
 
# Install Python tools (pyenv + uv)
brew install pyenv uv
 
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 
# Install Supabase CLI
brew install supabase/tap/supabase
 
# Setup gcloud (if needed)
brew install --cask google-cloud-sdk

Then reload your shell:

exec /bin/zsh

---

Core Development Tools

1. Homebrew (Package Manager)

Homebrew is the foundation for installing most tools on macOS.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Add to ~/.zshrc:

eval "$(/opt/homebrew/bin/brew shellenv)"

2. Git + GitHub CLI

brew install git gh git-delta

Authentication:

gh auth login

Configuration:

git config --global user.name "Your Name"
git config --global user.email "your@email.com"
git config --global core.pager delta  # Use delta for pretty diffs

3. 1Password CLI

Secure credential management for all Brainforge services.

brew install --cask 1password-cli

Authentication:

op signin

Verify:

op --version  # Should show 2.33.0+

---

Node.js Environment

nvm (Node Version Manager)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash

Add to ~/.zshrc:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Node.js 22 (LTS - Required)

nvm install 22
nvm use 22
nvm alias default 22

Verify:

node --version  # v22.22.1
npm --version   # 10.9.4

Package Managers

# Install pnpm (required for OpenWork)
npm install -g pnpm
 
# Verify
pnpm --version  # 10.32.1+

---

JavaScript/TypeScript Tools

Bun (Required for OpenWork)

Bun is used for OpenWork sidecar builds.

curl -fsSL https://bun.sh/install | bash

Add to ~/.zshrc (should be auto-added by installer):

export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

Verify:

bun --version  # 1.3.11+

Google Workspace CLI (gws)

For Google Sheets, Drive, Docs, Gmail, and Calendar operations.

npm install -g @googleworkspace/cli

Setup:

1. Create OAuth credentials in Google Cloud Console
2. Download client secret JSON
3. Place at ~/.config/gws/client_secret.json
4. Authenticate:

gws auth login -s sheets,drive,gmail,calendar
gws auth status

See google-workspace-cli-setup.md for full details.

OpenCode CLI (Required for OpenWork)

curl -fsSL https://opencode.ai/install | sh

Add to ~/.zshrc (auto-added by installer):

export PATH="$HOME/.opencode/bin:$PATH"

Verify:

opencode --version  # 1.2.27+

---

Python Environment

pyenv (Python Version Manager)

brew install pyenv pyenv-virtualenv

Add to ~/.zshrc:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Install Python 3.12:

pyenv install 3.12
pyenv global 3.12

uv (Modern Python Package Manager)

brew install uv

Verify:

uv --version  # 0.10.12+

---

Rust Toolchain

Required for OpenWork Tauri desktop builds.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Select default installation (option 1).

Add to ~/.zshrc:

source "$HOME/.cargo/env"

Verify:

rustc --version  # 1.94.0+
cargo --version  # 1.94.0+

---

Cloud & Database Tools

Google Cloud SDK (gcloud)

For GCP project access, Vertex AI, and Gemini.

brew install --cask google-cloud-sdk

Add to ~/.zshrc:

source "$(brew --prefix)/share/google-cloud-sdk/path.zsh.inc"
source "$(brew --prefix)/share/google-cloud-sdk/completion.zsh.inc"

Verify:

gcloud --version  # 559.0.0+

Railway CLI

For deployment and hosting.

brew install railway

Verify:

railway --version  # 4.33.0+

Supabase CLI

For local database operations and migrations.

brew install supabase/tap/supabase

Verify:

supabase --version  # 2.75.0+

ngrok

For local webhook testing.

brew install ngrok

Setup:

ngrok config add-authtoken <your-token>

Verify:

ngrok --version  # 3.37.2+

---

Productivity & Shell Tools

Modern Replacements for Standard Tools

Tool	Replaces	Purpose
eza	ls	Modern ls with git support
ripgrep (rg)	grep	Fast code search
fd	find	User-friendly find
fzf	-	Fuzzy finder
zoxide (z)	cd	Smart directory jumping
delta	diff	Pretty diffs
bat	cat	Syntax-highlighted cat
lazygit	-	TUI for git
atuin	history	Better shell history
starship	-	Customizable prompt

Install all:

brew install eza ripgrep fd fzf zoxide delta bat lazygit atuin starship

Shell Configuration

Add to ~/.zshrc:

# eza (alias ls)
alias ls='eza --icons=auto'
alias ll='eza -la --icons=auto'
alias tree='eza --tree --icons=auto'
 
# fzf
[ -f ~/.fzf.zsh ] && source ~/.fzf.zsh
 
# zoxide (initialize after fzf)
eval "$(zoxide init zsh)"
alias cd='z'
 
# atuin (better history)
eval "$(atuin init zsh)"
 
# starship prompt
eval "$(starship init zsh)"
 
# fzf integration with gh
eval "$(gh completion -s zsh)"

Install fzf key bindings:

$(brew --prefix)/opt/fzf/install

Recommended Starship Config

Create ~/.config/starship.toml:

# Use nerd font symbols
[character]
success_symbol = "[➜](bold green)"
error_symbol = "[✗](bold red)"
 
# Show Node version in JS projects
[nodejs]
format = "via [🟢 $version](bold green) "
detect_files = ["package.json", ".node-version"]
detect_extensions = ["js", "mjs", "cjs", "ts", "mts", "cts"]
 
# Show Python version
[python]
format = "via [🐍 $version](bold yellow) "
detect_files = ["requirements.txt", "pyproject.toml", "setup.py"]
detect_extensions = ["py"]
 
# Show Rust version
[rust]
format = "via [🦀 $version](bold red) "
detect_files = ["Cargo.toml"]
detect_extensions = ["rs"]
 
# Show git info
[git_branch]
symbol = "🌱 "
 
[git_status]
ahead = "⇡${count}"
diverged = "⇕⇡${ahead_count}⇣${behind_count}"
behind = "⇣${count}"
 
# Compact directory
[directory]
truncation_length = 3
truncation_symbol = "…/"

---

Security Tools

Gitleaks (Secret Detection)

Prevents committing secrets to the repo.

brew install gitleaks

Pre-commit hook:

# In repo root
gitleaks protect --staged

See gitleaks-setup.md for full pre-commit setup.

---

IDE & Editor Tools

Cursor IDE (Primary)

Download from cursor.sh

Shell command:

# Cursor should auto-install 'cursor' command
# Or manually add:
ln -s /Applications/Cursor.app/Contents/Resources/app/bin/cursor /usr/local/bin/cursor

VS Code (Optional)

brew install --cask visual-studio-code

---

Verification Checklist

Run this verification script to ensure everything is installed:

#!/bin/bash
echo "=== Brainforge CLI Verification ==="
echo ""
 
tools=(
  "Homebrew:brew:--version"
  "Git:git:--version"
  "GitHub CLI:gh:--version"
  "1Password CLI:op:--version"
  "Node.js:node:--version"
  "npm:npm:--version"
  "pnpm:pnpm:--version"
  "Bun:bun:--version"
  "gws:gws:--version"
  "OpenCode:opencode:--version"
  "Python:python3:--version"
  "uv:uv:--version"
  "Rust:rustc:--version"
  "Cargo:cargo:--version"
  "Google Cloud:gcloud:--version"
  "Railway:railway:--version"
  "Supabase:supabase:--version"
  "ngrok:ngrok:--version"
  "fzf:fzf:--version"
  "ripgrep:rg:--version"
  "fd:fd:--version"
  "eza:eza:--version"
  "zoxide:zoxide:--version"
  "delta:delta:--version"
  "atuin:atuin:--version"
  "lazygit:lazygit:--version"
  "starship:starship:--version"
  "jq:jq:--version"
  "wget:wget:--version"
)
 
for tool in "${tools[@]}"; do
  IFS=':' read -r name cmd arg <<< "$tool"
  if command -v $cmd &> /dev/null; then
    version=$($cmd $arg 2>&1 | head -1)
    echo "✅ $name: $version"
  else
    echo "❌ $name: NOT FOUND"
  fi
done

---

Project-Specific Setup

Platform (The Forge)

cd apps/platform
cp .env.example .env.local
npm ci --legacy-peer-deps
npm run dev  # Starts on port 3000

Dagster Pipelines

cd apps/dagster-pipelines
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
dagster dev -m pipelines.repository -p 3001

OpenWork

OpenWork is no longer developed from this monorepo. Use the separate brainforge-work repository if you need local Work setup.

---

Maintenance

Weekly Updates

# Update Homebrew packages
brew update && brew outdated
brew upgrade
 
# Update global npm packages
npm outdated -g
npm update -g
 
# Update Rust
rustup update
 
# Update Bun
bun upgrade
 
# Verify Node version
node --version  # Should be v22.x

Troubleshooting

Node version issues:

nvm use 22
nvm alias default 22

1Password CLI not found:

eval "$(/opt/homebrew/bin/brew shellenv)"
op signin

Python not from pyenv:

which python3  # Should show ~/.pyenv/shims/python3
pyenv rehash

Cargo/rustc not found:

source "$HOME/.cargo/env"

---

Related Guides

• 1Password CLI Setup
• Google Workspace CLI Setup
• OpenWork Local Build Setup - archived in this monorepo; use brainforge-work for current Work setup
• GitHub CLI Setup
• Supabase Query Access

---

Questions?

Contact the AI Team or ask in the engineering channel.