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

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:

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【^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:

   open bitchat.xcodeproj

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

   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):

   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:

   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):

   just check

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

   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 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:

  just clean

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

  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. 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.

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}