# How to Run BitChat on Different Operating Systems: macOS, iOS Simulator, and Cross-Platform Workflows

> Learn how to run BitChat on macOS and iOS simulator using Xcode. Explore streamlined cross-platform workflows with the just task runner for a seamless development experience.

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

---

**BitChat runs natively on macOS and iOS simulator through Xcode, with streamlined cross-platform commands available via the `just` task runner.**

BitChat is a Swift-based peer-to-peer chat application built by [permissionlesstech](https://github.com/permissionlesstech/bitchat). Because it relies on Apple-specific frameworks like **UIKit**, **AppKit**, and **CoreBluetooth**, running BitChat requires the Xcode toolchain—limiting native execution to macOS and iOS environments. This guide covers every supported method to run BitChat on different operating systems, from direct Xcode builds to automated `just` workflows.

---

## Running BitChat on macOS

The simplest way to run BitChat is opening `bitchat.xcodeproj` in Xcode and selecting the **"bitchat (macOS)"** scheme.

### From the Xcode GUI

1. Open `bitchat.xcodeproj`
2. Select **bitchat (macOS)** from the scheme dropdown
3. Press **⌘ R** to build and run

### From the Command Line

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

```

This compiles the native macOS client without modifying source files or entitlements. The resulting binary is placed in Xcode's `DerivedData` directory (already ignored by Git).

---

## Running BitChat on iOS Simulator

BitChat ships with a dedicated **"bitchat (iOS)"** scheme for simulator testing.

### List Available Simulators

```bash
xcodebuild -showdestinations -project bitchat.xcodeproj -scheme "bitchat (iOS)"

```

### Build and Run on a Specific Device

```bash
xcodebuild -project bitchat.xcodeproj -scheme "bitchat (iOS)" -destination 'platform=iOS Simulator,name=iPhone 17,OS=latest' test

```

Replace `iPhone 17` with any simulator returned by the `showdestinations` command. The default target assumes `iPhone 17` with the latest OS version.

---

## Cross-Platform Workflow with Just

The [`Justfile`](https://github.com/permissionlesstech/bitchat/blob/main/Justfile) provides **OS-agnostic shortcuts** for developers who prefer command-line workflows or automated builds.

### Install Just

```bash
brew install just

```

### Available Commands

| Command | Action |
|---------|--------|
| `just check` | Run static analysis and lint checks |
| `just run` | Build and launch the macOS scheme |
| `just build` | Compile macOS scheme without running |
| `just clean` | Remove `.DerivedData/` and `.build/` artifacts |
| `just test` | Execute SwiftPM test suite on macOS |
| `just test-ios` | Run tests on iPhone 17 simulator |

All `just` commands operate safely—they never modify source files or Git history.

### Example Workflow

```bash
just check    # Verify code quality

just run      # Launch macOS app

just test-ios # Validate on iOS simulator

just clean    # Clean build artifacts

```

---

## Linux and Windows Limitations

**BitChat cannot run natively on Linux or Windows.** The codebase depends on Apple-exclusive APIs documented in [`ARCHITECTURE_V2.md`](https://github.com/permissionlesstech/bitchat/blob/main/ARCHITECTURE_V2.md), including:

- **UIKit** and **AppKit** for user interfaces
- **CoreBluetooth** for peer-to-peer networking
- **Xcode toolchain** for compilation

Developers on non-Apple platforms have three alternatives:

1. **macOS virtual machine** with Xcode installed
2. **CI/CD service** providing macOS runners (GitHub Actions, Buildkite)
3. **Remote macOS development environment** for builds and testing

---

## Key Project Files

Understanding these files helps troubleshoot platform-specific issues:

| File | Purpose |
|------|---------|
| `Justfile` | Task automation (`just run`, `just test-ios`, etc.) |
| [`README.md`](https://github.com/permissionlesstech/bitchat/blob/main/README.md) | Primary documentation for macOS/iOS/`just` workflows |
| [`Package.swift`](https://github.com/permissionlesstech/bitchat/blob/main/Package.swift) | Swift Package Manager manifest for command-line builds |
| `bitchat.xcodeproj/project.pbxproj` | Xcode project definitions for both schemes |
| `bitchatTests/` | Test suite executed via `just test` or `just test-ios` |

---

## Summary

- **macOS**: Open `bitchat.xcodeproj` and run the **bitchat (macOS)** scheme, or use `just run`
- **iOS Simulator**: Target any simulator with `xcodebuild` using the **bitchat (iOS)** scheme, or run `just test-ios`
- **Cross-platform**: Install `just` to abstract Xcode commands across environments
- **Linux/Windows**: Require macOS VM or CI service due to Apple framework dependencies

---

## Frequently Asked Questions

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

No. BitChat requires Apple's **UIKit**, **AppKit**, and **CoreBluetooth** frameworks, which are exclusive to Apple's platforms. You must use a macOS virtual machine, remote macOS environment, or CI service with Xcode support.

### What is the fastest way to build and run BitChat?

Use **`just run`** from the repository root. This single command triggers the macOS scheme build and launch without opening Xcode, making it ideal for rapid iteration.

### How do I run tests on a different iOS simulator?

First list available destinations with `xcodebuild -showdestinations`, then substitute your device name in the `-destination` flag. For example: `platform=iOS Simulator,name=iPhone 15 Pro,OS=17.5`.

### Does running BitChat modify source files or Git history?

No. All documented workflows—including direct `xcodebuild` commands and `just` tasks—are read-only operations. The `just clean` command only removes build artifacts in `.DerivedData/` and `.build/` directories.