# How to Set Up the Development Environment for Bitchat: Complete Swift Setup Guide

> Set up the bitchat development environment easily. Clone the repo, install Xcode & Swift, configure settings, and build with just build or Xcode.

- Repository: [permissionlesstech/bitchat](https://github.com/permissionlesstech/bitchat)
- Tags: getting-started
- Published: 2026-08-06

---

**Set up the bitchat development environment by cloning the repository, installing Xcode 15+ and Swift 5.9, configuring `Local.xcconfig` from the example, and building with `just build` or Xcode.**

Bitchat is a Swift-based, peer-to-peer messaging application that supports iOS, macOS, and optional Tor networking via the **Arti** XCFramework. This guide walks through the complete development environment setup for contributing to or extending [permissionlesstech/bitchat](https://github.com/permissionlesstech/bitchat), using the repository's documented workflow and tooling.

## Prerequisites for Bitchat Development

Before cloning the repository, ensure your system meets these requirements:

- **Xcode 15 or later** with Swift 5.9+
- **Swift Package Manager** (bundled with Xcode)
- **just** command runner (optional but recommended): `brew install just`
- **Git** for source control

The bitchat project uses **SPM** for dependency management and includes pre-built local packages in the `localPackages/` directory.

## Step 1: Clone and Open the Repository

Fetch the source code and open the Xcode project:

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

```

The `bitchat.xcodeproj` file is generated from the Swift package manifest. Opening it triggers automatic package resolution for dependencies declared in [`Package.swift`](https://github.com/permissionlesstech/bitchat/blob/main/Package.swift).

## Step 2: Configure Local Build Settings

Bitchat uses **xcconfig files** for environment-specific build variables. Create your local configuration from the provided template:

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

```

Open `Configs/Local.xcconfig` to customize:

- API endpoint URLs
- Feature flags
- Compiler definitions

This file is **gitignored** by default, preventing accidental commits of local credentials or debug settings.

## Step 3: Enable Clear-Net for Faster Local Testing (Optional)

By default, bitchat routes all traffic through Tor using the Arti framework. For rapid iteration on simulators or trusted local networks, you can disable Tor with the `BITCHAT_DEV_ALLOW_CLEARNET` flag.

Add to `Configs/Local.xcconfig`:

```swift
BITCHAT_DEV_ALLOW_CLEARNET = YES

```

**Warning:** As documented in [[`docs/TOR-INTEGRATION.md`](https://github.com/permissionlesstech/bitchat/blob/main/docs/TOR-INTEGRATION.md)](https://github.com/permissionlesstech/bitchat/blob/main/docs/TOR-INTEGRATION.md), this exposes your traffic to network observers. Never use this flag in production builds or when testing with sensitive data.

## Step 4: Resolve Swift Packages

Xcode automatically resolves dependencies on first build. To resolve manually via command line:

```bash
swift package resolve

```

The [`Package.swift`](https://github.com/permissionlesstech/bitchat/blob/main/Package.swift) manifest declares three local packages:

- **BitLogger** – structured logging utilities
- **BitFoundation** – shared data types and extensions
- **Arti** – pre-built Tor client XCFramework in `localPackages/Arti/`

No additional steps are needed for the Arti framework; Xcode links it automatically via the package manifest.

## Step 5: Build and Run Bitchat

### Using Xcode

Select your target platform (iOS Simulator or macOS) and press **⌘ R** to build and run.

### Using Just Commands

The `Justfile` provides consistent shortcuts for common tasks:

```bash

# Build the default scheme

just build

# Run the full test suite

just test

# Build and launch iOS simulator

just run-ios

```

All targets are defined in the repository's [`Justfile`](https://github.com/permissionlesstech/bitchat/blob/main/Justfile), which wraps `xcodebuild` with sensible defaults.

## Step 6: Run Tests

Execute the comprehensive XCTest suites covering protocol handling, view models, and BLE mesh logic:

```bash
just test

```

Or run specific tests with `xcodebuild`:

```bash
xcodebuild test \
  -scheme bitchat \
  -destination 'platform=iOS Simulator,name=iPhone 15,OS=latest' \
  -only-testing:bitchatTests/ChatViewModelTests

```

Test files reside in `bitchatTests/` with mirror structure to the source tree.

## Step 7: Verify Build Reproducibility (Recommended)

For production builds or security audits, follow [[`docs/VERIFYING-A-BUILD.md`](https://github.com/permissionlesstech/bitchat/blob/main/docs/VERIFYING-A-BUILD.md)](https://github.com/permissionlesstech/bitchat/blob/main/docs/VERIFYING-A-BUILD.md). This ensures your compiled binary matches the published source exactly—a critical step for a privacy-focused messaging app.

## Key Project Structure

Understanding where code lives accelerates development:

| Directory | Purpose |
|-----------|---------|
| `bitchat/Services/` | Core networking stack (Nostr transport, Noise encryption, gateways) |
| `bitchat/Services/BLE/` | Bluetooth Low Energy mesh networking implementation |
| `bitchatTests/` | XCTest suites for unit and integration testing |
| `Configs/` | Build configuration templates and local overrides |
| `localPackages/` | Vendored dependencies including `Arti.xcframework` |

## Rapid Development Workflow Example

Complete setup from fresh clone to running tests:

```bash

# 1. Clone

git clone https://github.com/permissionlesstech/bitchat.git && cd bitchat

# 2. Configure

cp Configs/Local.xcconfig.example Configs/Local.xcconfig

# Edit Local.xcconfig to add: BITCHAT_DEV_ALLOW_CLEARNET = YES

# 3. Build and test

just build
just test

# 4. Launch in simulator

just run-ios

```

## Summary

- **Install Xcode 15+** with Swift 5.9 to meet baseline requirements
- **Copy `Local.xcconfig`** from the example file to enable customizable builds
- **Add `BITCHAT_DEV_ALLOW_CLEARNET = YES`** for clear-net development speed (never for release)
- **Use `just` commands** for reproducible builds, tests, and simulator launches
- **Reference [`Package.swift`](https://github.com/permissionlesstech/bitchat/blob/main/Package.swift)** for dependency structure and `Justfile` for automation
- **Verify release builds** per [`docs/VERIFYING-A-BUILD.md`](https://github.com/permissionlesstech/bitchat/blob/main/docs/VERIFYING-A-BUILD.md) for binary authenticity

## Frequently Asked Questions

### What happens if I skip the Local.xcconfig step?

The build will fail with missing configuration values. The `Configs/Local.xcconfig.example` template provides required placeholder definitions that Xcode expects during compilation. Without creating `Local.xcconfig`, preprocessor macros and bundle identifiers remain undefined.

### Can I develop bitchat without Tor?

Yes, but only for development. Set `BITCHAT_DEV_ALLOW_CLEARNET = YES` in `Local.xcconfig` to route traffic directly over HTTPS instead of through the Arti Tor client. This dramatically improves build-test cycles but removes anonymity protections. The flag is compile-time only and disabled in release configurations.

### Do I need to rebuild the Arti XCFramework?

No. The pre-built `Arti.xcframework` in `localPackages/Arti/` is ready for immediate use. Rebuilding requires Rust toolchain setup and is unnecessary for application development. The Swift package in [`Package.swift`](https://github.com/permissionlesstech/bitchat/blob/main/Package.swift) handles linking automatically.