# How to Set Up BitChat on a Local Machine: Complete Build Guide

> Build and set up BitChat on your local machine with this complete guide. Clone the repository, install dependencies, and build easily.

- Repository: [permissionlesstech/bitchat](https://github.com/permissionlesstech/bitchat)
- Tags: how-to-guide
- Published: 2026-08-01

---

**You can set up BitChat locally by cloning the repository, installing Xcode 14+ and the `just` task runner, then building with either `xcodebuild` or the `just run` command.**

BitChat is a peer-to-peer messaging application that combines a local Bluetooth mesh for offline communication with the Nostr protocol for internet-wide messaging. The repository at `permissionlesstech/bitchat` ships with a full Xcode project and a `Justfile` workflow, enabling you to compile and run the app on macOS or the iOS simulator using straightforward command-line tools.

## Prerequisites

Before building, ensure your development environment meets these requirements:

- **Xcode 14 or later** – Required for `xcodebuild` and the iOS/macOS schemes. Install from the Mac App Store or run `xcode-select --install`.
- **Swift 5.9+** – Bundled with Xcode and required for the SwiftPM test suite.
- **Homebrew** – Optional but recommended for installing the `just` task runner.
- **just** – Install via `brew install just` to use the repository's command-line recipes defined in `Justfile`【^cache/repos/github.com/permissionlesstech/bitchat/main/Justfile#L11-L48】.

## Clone the Repository

Start by cloning the source code to your local machine:

```bash
git clone https://github.com/permissionlesstech/bitchat.git
cd bitchat

```

The repository includes documentation on verifying code signatures in the **"Getting a copy you can trust"** section of [`README.md`](https://github.com/permissionlesstech/bitchat/blob/main/README.md)【^cache/repos/github.com/permissionlesstech/bitchat/main/README.md#L108-L112】.

## Build Options

You have two primary methods to compile BitChat locally: using Xcode directly for IDE debugging, or using the `just` command-line workflow for rapid iteration.

### Option A: Build with Xcode (Recommended for Debugging)

This method opens the project in Xcode and allows full debugging capabilities.

1. **Open the project**:

   ```bash
   open bitchat.xcodeproj
   ```

2. **Configure code signing** (required for device builds, optional for macOS simulator):

   ```bash
   cp Configs/Local.xcconfig.example Configs/Local.xcconfig
   ```

   Edit `Configs/Local.xcconfig` and replace `$(TEAM_ID)` with your Apple Developer team identifier. The project's entitlements reference `$(APP_GROUP_ID)`, so no further configuration changes are needed【^cache/repos/github.com/permissionlesstech/bitchat/main/README.md#L118-L124】.

3. **Build the macOS scheme** (Debug configuration, unsigned):

   ```bash
   xcodebuild -project bitchat.xcodeproj \
     -scheme "bitchat (macOS)" \
     -configuration Debug \
     CODE_SIGNING_ALLOWED=NO \
     build
   ```

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

4. **Launch the application**:

   ```bash
   open .DerivedData/Build/Products/Debug/bitchat.app
   ```

### Option B: Build with `just` (Command-Line Workflow)

The `Justfile` provides recipes that wrap `xcodebuild` with sensible defaults for faster development cycles.

1. **Verify your environment** (runs the same checks as CI):

   ```bash
   just check
   ```

2. **Build and run** (compiles the macOS app and immediately launches it):

   ```bash
   just run
   ```

3. **Run the test suite**:

   - SwiftPM unit tests: `just test`
   - iOS simulator tests: `just test-ios` (requires an iPhone 17 simulator or any available iOS device)

Both `just test` and `just test-ios` invoke the test targets defined in [`Package.swift`](https://github.com/permissionlesstech/bitchat/blob/main/Package.swift) and the Xcode project schemes.

## Clean Build Artifacts

When you need to reset your build environment, use these `just` recipes:

- **Local clean** – Removes derived data and SwiftPM build cache:

  ```bash
  just clean
  ```

- **Full nuke** – Deletes nested package caches in addition to build artifacts:

  ```bash
  just nuke
  ```

These commands are safe and only target build artifacts, never modifying tracked source files【^cache/repos/github.com/permissionlesstech/bitchat/main/Justfile#L49-L61】.

## Verify Your Build

For cryptographic assurance that your compiled binary matches the release manifest, follow the verification steps in [`docs/VERIFYING-A-BUILD.md`](https://github.com/permissionlesstech/bitchat/blob/main/docs/VERIFYING-A-BUILD.md). This document explains how to compare binary hashes against the per-release manifest to ensure supply-chain integrity.

## Summary

- **BitChat** uses a dual-transport architecture (Bluetooth mesh + Nostr) and requires **Xcode 14+** and **Swift 5.9+** to build.
- Clone the repository, then choose between **Xcode IDE** builds for debugging or the **`just`** command-line workflow for speed.
- Configure signing by copying `Configs/Local.xcconfig.example` to `Configs/Local.xcconfig` and setting your team ID.
- Use `just run` to build and launch, `just test` for unit tests, and `just clean` to reset build artifacts.
- Verify builds cryptographically using the documentation in [`docs/VERIFYING-A-BUILD.md`](https://github.com/permissionlesstech/bitchat/blob/main/docs/VERIFYING-A-BUILD.md).

## Frequently Asked Questions

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

BitChat is built for Apple's ecosystem and requires Xcode, which is only available on macOS. The `bitchat.xcodeproj` and [`Package.swift`](https://github.com/permissionlesstech/bitchat/blob/main/Package.swift) files define macOS and iOS targets specifically, making Linux and Windows unsupported for local development.

### Do I need an Apple Developer account to build BitChat?

You do not need a paid Apple Developer account to build and run the macOS Debug version locally using `CODE_SIGNING_ALLOWED=NO`. However, you will need a valid team ID (free or paid) configured in `Configs/Local.xcconfig` if you intend to run the app on a physical iOS device or distribute the binary.

### What does the `just check` command verify?

The `just check` recipe validates that your environment has the required Xcode version, command-line tools, and dependencies installed. It runs the same sanity checks used in the repository's CI pipeline to ensure your machine can successfully execute `just run` and `just test`.

### How do I run BitChat on the iOS simulator instead of macOS?

Use the `just test-ios` command, which builds the project for the iOS simulator scheme and executes tests. For interactive debugging in the simulator, open `bitchat.xcodeproj` in Xcode, select an iPhone simulator target (such as iPhone 17), and press Run.