# How to Set Up a Local Instance of FluidVoice: Complete macOS Development Guide

> Learn to set up a local FluidVoice instance on macOS. Clone the repo, build in Xcode, and grant permissions for real-time dictation with this complete guide.

- Repository: [ALTIC/FluidVoice](https://github.com/altic-dev/FluidVoice)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Setting up a local FluidVoice instance requires cloning the SwiftUI-based macOS app from GitHub, building it in Xcode with proper code signing, and granting Microphone and Accessibility permissions to enable real-time voice-to-text dictation.**

FluidVoice is a **macOS-only voice-to-text dictation application** built with **SwiftUI** and a modular architecture of Swift services. When you run a local instance, you execute the same production codebase that powers the released app, compiled directly from source. This guide walks through the complete setup process using the actual source files from [`altic-dev/FluidVoice`](https://github.com/altic-dev/FluidVoice).

## Prerequisites for Local FluidVoice Development

Before building, ensure your environment meets these requirements:

- **macOS** (FluidVoice is macOS-only)
- **Xcode** with Swift Package Manager support
- **Apple Development certificate** for code signing (free "Personal Team" certificates work)
- **Microphone** and **Accessibility** permissions available to grant

The app cannot run on iOS, iPadOS, or Linux due to its dependency on **CoreAudio** and **macOS Accessibility APIs**.

## Step-by-Step Setup Process

### 1. Clone the FluidVoice Repository

Start by cloning the repository and entering the project directory:

```bash
git clone https://github.com/altic-dev/FluidVoice.git
cd FluidVoice

```

### 2. Open the Xcode Project

The project file `Fluid.xcodeproj` contains the `Fluid` target and all **Swift Package Manager (SPM)** dependencies:

```bash
open Fluid.xcodeproj

```

### 3. Configure Code Signing

FluidVoice requires an **Apple Development certificate** for proper signing. The repository includes [`build.sh`](https://github.com/altic-dev/FluidVoice/blob/main/build.sh) to automate this process:

```bash
./build.sh          # signed build using first available development identity

./build.sh unsigned # unsigned build for CI environments

```

The script extracts your development team automatically, or you can set `FLUIDVOICE_DEVELOPMENT_TEAM` manually. If no certificate exists, **Xcode prompts you to create a free "Personal Team" certificate**.

Without proper signing, macOS **Accessibility permissions** (required for typing into other apps) will not function correctly.

### 4. Build and Run the Application

In Xcode:

1. Select the **Fluid** scheme
2. Press **Run** (⌘R)

The compiled binary appears at `DerivedData/Build/Products/Debug/FluidVoice Debug.app`.

For command-line builds:

```bash
./build.sh

```

### 5. Grant Required System Permissions

On first launch, macOS requests two essential permissions:

| Permission | Purpose | Source Component |
|------------|---------|----------------|
| **Microphone** | Audio capture for speech recognition | [`FluidAudioProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/FluidAudioProvider.swift) |
| **Accessibility** | Type transcription into any application | `TextSelectionService` via `MenuBarManager` |

To manually open system preferences, use the menu bar shortcut provided by `MenuBarManager.openPreferencesFromUI()`.

### 6. Optional: Enable Fluid Intelligence

**Fluid Intelligence** provides on-device AI enhancement for capitalization, punctuation, and context-aware formatting. During onboarding:

1. Download the optional AI model (~3.5 GB)
2. The `LocalAPI` server ([`LocalAPIServer.swift`](https://github.com/altic-dev/FluidVoice/blob/main/LocalAPIServer.swift)) handles the download
3. Models are cached locally; no network traffic occurs after download

To enable programmatically:

```swift
let aiService = PrivateAIProvider.shared
aiService.enableLocalModel(at: URL(fileURLWithPath: "/path/to/fluid_intelligence.bin"))

```

## Core Architecture Overview

Understanding the component structure helps with debugging and customization:

| Component | File Path | Responsibility |
|-----------|-----------|--------------|
| **`FluidApp`** | [`Sources/Fluid/fluidApp.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/fluidApp.swift) | `@main` entry point; creates SwiftUI window, injects `MenuBarManager` and `AppServices` |
| **`MenuBarManager`** | [`Sources/Fluid/Services/MenuBarManager.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/MenuBarManager.swift) | Status-item management, overlay lifecycle, user action routing |
| **`FluidAudioProvider`** | [`Sources/Fluid/Services/FluidAudioProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/FluidAudioProvider.swift) | CoreAudio bridge feeding raw PCM to ASR providers |
| **ASR Services** | [`Sources/Fluid/Services/WhisperProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/WhisperProvider.swift) (and siblings) | `TranscriptionProvider` implementations: `WhisperProvider`, `ParakeetRealtimeProvider`, `NemotronProvider` |
| **`PrivateAIProvider`** | [`Sources/Fluid/Services/PrivateAIProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/PrivateAIProvider.swift) | Optional cloud or local AI post-processing |
| **`LocalAPIServer`** | [`Sources/Fluid/Services/LocalAPI/LocalAPIServer.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/LocalAPI/LocalAPIServer.swift) | On-device HTTP server for Fluid Intelligence inference |
| **`AnalyticsService`** | [`Sources/Fluid/Analytics/AnalyticsService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Analytics/AnalyticsService.swift) | Anonymous usage collection (opt-in); guarantees no audio/text leaves device without explicit cloud AI enablement |

## Running Integration Tests

Verify your local instance with the test suite:

```bash
xcodebuild test -project Fluid.xcodeproj -scheme Fluid -destination 'platform=macOS'

```

## Programmatic Control Examples

### Custom Launch Script (CI/Automated Demos)

```swift
import SwiftUI

@main
struct DemoLauncher {
    static func main() {
        // Directly instantiate the main app struct
        FluidApp.main()
    }
}

```

### Trigger Recording from Code

```swift
let asrService = ASRService.shared   // Concrete TranscriptionProvider subclass
asrService.startRecording()          // Begins audio capture via FluidAudioProvider
// … transcription streams via partialTranscription …
asrService.stopRecording()           // Triggers finalTranscription and overlay hide

```

## Troubleshooting Common Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| Accessibility permission denied | Unsigned build or revoked certificate | Use [`./build.sh`](https://github.com/altic-dev/FluidVoice/blob/main/./build.sh) with valid development team |
| No audio input | Microphone permission blocked | Check Security & Privacy → Microphone |
| Overlay doesn't appear | `MenuBarManager` initialization failed | Verify `AppServices` singleton creation in [`fluidApp.swift`](https://github.com/altic-dev/FluidVoice/blob/main/fluidApp.swift) |
| Local AI won't download | `LocalAPIServer` port conflict | Check port availability; server logs in Console |

## Summary

- **Clone** from `https://github.com/altic-dev/FluidVoice.git`
- **Build** using Xcode or [`./build.sh`](https://github.com/altic-dev/FluidVoice/blob/main/./build.sh) with proper code signing
- **Grant** Microphone and Accessibility permissions on first launch
- **Enable** optional Fluid Intelligence for on-device AI enhancement
- **Test** with `xcodebuild test` or the scheme's Run action

A properly configured local FluidVoice instance provides full access to the same real-time dictation, multi-provider ASR switching, and optional AI post-processing available in production releases.

## Frequently Asked Questions

### Can I run FluidVoice on Windows or Linux?

No. FluidVoice is **macOS-only** due to dependencies on **CoreAudio** for audio capture and **macOS Accessibility APIs** for text insertion. The entire architecture in `Sources/Fluid/Services/` assumes Apple platform frameworks. Porting would require replacing [`FluidAudioProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/FluidAudioProvider.swift) and `TextSelectionService` with platform-specific alternatives.

### Do I need a paid Apple Developer account?

No. A **free "Personal Team" certificate** from Xcode satisfies the signing requirement. The [`build.sh`](https://github.com/altic-dev/FluidVoice/blob/main/build.sh) script automatically configures this, or you can create one when Xcode prompts during first build. Paid accounts are only needed for App Store distribution.

### What data leaves my machine when using FluidVoice?

**Nothing by default.** According to [`AnalyticsService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AnalyticsService.swift), the app collects only anonymous usage statistics (opt-in). Audio and transcripts remain on-device unless you deliberately enable a cloud AI provider. The optional Fluid Intelligence model runs entirely through [`LocalAPIServer.swift`](https://github.com/altic-dev/FluidVoice/blob/main/LocalAPIServer.swift) without network calls after initial download.