How to Set Up Your Local Ito AI Server on macOS (Developer Guide)

What you’ll build: a local transcription server Ito can talk to, so your speech-to-text runs on your Mac, powered by the Groq API for high-speed transcription. This mirrors the developer setup in the repo’s Building from Source and Server docs. (GitHub)

‍

Prerequisites (macOS)

• macOS: App targets macOS
• Install via Homebrew or a version manager (e.g., nvm)

‍Xcode Command Line Tools: Needed for native builds:

• xcode-select --install
• Bun (JS runtime & scripts): Project’s designated JS runtime & package manager. Note: Bun supports macOS; Ventura (13) or later is recommended, but Bun’s site doesn’t explicitly require 13+. (bun.sh)
• Rust toolchain: For Ito’s native components (performance). Install via rustup.
• Docker Desktop: Used to run the local Postgres DB (via Docker Compose) during dev.

‍

‍

Step 1 — Install the Tooling

# Node.js (via Homebrew)

brew install node

‍

# Bun (official script)

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

# or via Homebrew

# brew install bun

‍

# Rust (rustup)

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

‍

# Docker Desktop for Mac

brew install --cask docker

# …or download from Docker's site if you prefer

‍

Tip: After installing Bun or Rust, open a new terminal so your $PATH is refreshed. Verify with:

bun --version

rustc --version

‍

Step 2 — Clone Ito and Bootstrap

# Clone the repository

git clone https://github.com/heyito/ito.git

cd ito

‍

# Install App dependencies

bun install

# Create top-level environment file

cp .env.example .env

# Build native components (Rust binaries)

bun build:rust:mac

‍

These steps match the repo’s Building from Source instructions. For a local setup, you generally don’t need to modify the root .env. (GitHub)

‍

Step 3 — Configure the Server with Groq

Navigate to the server and install dependencies:

cd server

cp .env.example .env

bun install

‍

Get a Groq API Key

• Go to the Groq console and create an API key: https://console.groq.com/

‍

‍Edit server/.env

Local dev only: set REQUIRE_AUTH=false to bypass auth checks while developing. Add your Groq key:

# ... other variables

REQUIRE_AUTH=false

GROQ_API_KEY="gsk_YourCopiedApiKeyFromGroq"

# ... other variables

‍

‍Heads up: The root README says “Edit with your API keys,” but exact variable names live in server/.env.example. Use that file as the source of truth in case names change (e.g., model env var). (GitHub)

‍

Alternative (shell export)

export GROQ_API_KEY="gsk_YourCopiedApiKeyFromGroq"

‍

Step 4 — Start Postgres & Run Migrations

Make sure Docker Desktop is running before you start.

# Starts a local Postgres container via Docker (Compose)

bun run local-db-up

‍

# Applies database migrations

bun run db:migrate

‍

This uses a dev container with sensible defaults; data persists in a Docker volume.

‍

Step 5 — Run the Ito Server (keep this tab open)

Start the local gRPC server the desktop app will talk to:

# from the server/ directory

bun run dev

‍

You should see logs indicating the RPC server is running (the log shows the port; if 3000 is occupied, it may differ).

‍

Step 6 — Launch the Ito App in Dev Mode

Open a new terminal (recommended), or reuse the server terminal.

‍

Option A — New terminal:

# from anywhere

cd /path/to/ito          # enter the repo root

bun run dev

‍

On the first run, macOS will prompt you to grant Microphone and Accessibility permissions. Ito needs the mic for audio input and accessibility to type into other applications.

When the app launches, select the Self-hosted option in onboarding. The app auto-enables self-hosted mode once a healthy local server is detected. These app and dev steps mirror the repo README. (GitHub)

‍

Quick Copy-Paste Summary (Mac)

# 0) Tools (install once)

brew install node

xcode-select --install

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

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

brew install --cask docker

‍

# 1) Clone & bootstrap

git clone https://github.com/heyito/ito.git

cd ito

bun install

cp .env.example .env

./build-binaries.sh

‍

# 2) Configure & run the server

cd server

cp .env.example .env

# --> MANUALLY EDIT server/.env: set REQUIRE_AUTH=false (for local dev)

#     and add your GROQ_API_KEY (or export it in your shell)

bun install

bun run local-db-up

bun run db:migrate

bun run dev   # keep this running

‍

# 3) Launch the app

# Option A: In a NEW terminal

cd /path/to/ito

bun run dev

‍

Troubleshooting (macOS)

• Bun not found
  Re-open your terminal so your $PATH updates after installation. Verify with bun --version. Bun must be version 1.2.0+
  
  
• Docker errors / DB won’t start
  Ensure Docker Desktop is running before bun run local-db-up. If migrations fail, confirm the container is healthy, then rerun bun run db:migrate.
  
  
• Server errors on startup
  Double-check REQUIRE_AUTH=false (for local dev) and that GROQ_API_KEY is set (in server/.env or exported). Also verify Node.js is v20+ (node -v). These match the repo’s dev instructions. (GitHub)
  
  
• Port conflicts
  If another process is using the server’s default port, stop it or change the port via env/config. The server log will show which port it is bound to.
  
  
• App can’t type or hear you
  Grant Accessibility and Microphone permissions in System Settings → Privacy & Security. You may need to grant these to your terminal app (Terminal, iTerm2) as well.

• ‍Self-host toggle missing/disabled
  The app auto-enables self-hosted mode only when a healthy local server is detected. Ensure the bun run dev process in server/ is still running without errors and the DB is up.

‍

Pointers to the Repo & Docs

• Main README (build + app dev steps): mirrors your Step 2, Step 5, Step 6 flow. (GitHub)
  
  
• Website (Mac download CTA): confirms the “Free Download for Mac” messaging. (heyito.ai)

• ‍Bun (platform info): general macOS support; no explicit “13+ required” line—hence the softer wording. (bun.sh)