> ## Documentation Index
> Fetch the complete documentation index at: https://docs.edge0.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS Guide

Edge0 can run models locally on an iPhone. This guide explains how to build and install the app through Xcode. The model is bundled with the app at build time, so you do not need to transfer it to the phone separately after installation.

## Device and prerequisites

* An iPhone, iOS 17 or later, with Developer Mode enabled.
* An Apple Silicon Mac with Xcode installed (the project uses Swift tools 6.1).
* An Apple Developer Team configured for code signing in Xcode.
* Git and Python 3.10+. Python is used only to download models and convert 35B.

We tested 8B and 35B on an **iPhone 16 Pro (iOS 26.6.2)**.

An app that includes 8B is about **5 GB**, and one that includes 35B is about **20 GB**. Before downloading, leave enough space on both the Mac and the iPhone.

**1. Get the source and prepare the tools**

Run in a Mac terminal:

```bash theme={null}
git clone https://github.com/Edge0-AI/Edge0.git
cd Edge0/ios
python3 -m venv .venv-tools
.venv-tools/bin/python -m pip install --upgrade pip huggingface_hub numpy
```

Run the subsequent commands in the `Edge0/ios` directory. You can prepare 8B only, 35B only, or both.

**2. Prepare the model**

The contents of the `Models/` directory are bundled into the app at build time. Place the model there before building.

### Using 8B

8B can be bundled as downloaded:

```bash theme={null}
.venv-tools/bin/hf download Edge0/Edge0-8B-A1B-preview \
  --local-dir Models/Edge0-8B-A1B-preview
```

### Using 35B

35B requires a file-layout conversion to improve model-loading performance on iPhone. The conversion reorganizes the files without changing the model weights. Store the original download in `checkpoints/` and write the converted files to `Models/repacked/`:

```bash theme={null}
mkdir -p checkpoints
.venv-tools/bin/hf download Edge0/Edge0-35B-A3B-preview \
  --local-dir checkpoints/Edge0-35B-A3B-preview

SOURCE=checkpoints/Edge0-35B-A3B-preview
OUTPUT=Models/repacked

.venv-tools/bin/python tools/repack_experts.py pack "$SOURCE" "$OUTPUT"
.venv-tools/bin/python tools/repack_experts.py resident "$SOURCE" "$OUTPUT"
.venv-tools/bin/python tools/repack_experts.py verify "$SOURCE" "$OUTPUT"
.venv-tools/bin/python tools/convert_tokenizer.py "$SOURCE" "$OUTPUT/tokenizer.bin"
.venv-tools/bin/python tools/convert_pregate.py \
  "$SOURCE/prerouter_edge0_35b.safetensors" \
  "$OUTPUT/prerouter-stacked.safetensors"
cp "$SOURCE/lora_edge0_35b.safetensors" "$OUTPUT/"
```

Each step should complete successfully; `verify` checks the conversion result. If any step reports an error, resolve it before continuing.

Keep the original download outside `Models/` so it is not bundled into the app again.

**3. Configure signing in Xcode and install**

1. Open `Edge0PhoneProbe.xcodeproj`.
2. Select the **Edge0Phone** target.
3. In **Signing & Capabilities**, replace `com.example.edge0phone` in the **Bundle Identifier** with your own unique identifier.
4. Select your Apple Developer Team.
5. Connect the iPhone, confirm the phone trusts this Mac, and confirm Developer Mode is enabled.
6. Select the iPhone as the run target and click **Run**.

The first build may need to download Swift package dependencies.

If Xcode reports a missing Metal compiler, run the following in a terminal and retry:

```bash theme={null}
xcodebuild -downloadComponent MetalToolchain
```

**4. Select a model and start chatting**

1. Open the app.
2. Select **Edge0 8B** or **Edge0 35B**.
3. Wait for the model to finish preparing.
4. Enter a question, or tap one of the example prompts in the interface.

Each response shows generation speed and memory usage; the values vary by device and content.

Switching models unloads the current one. **New chat** clears the current conversation and starts a new one.

## The app shows **Not included**

This means the model was not bundled into the currently installed app. Check:

* Whether 8B is at `Models/Edge0-8B-A1B-preview/`.
* Whether 35B completed all conversion steps and is at `Models/repacked/`.
* Whether you rebuilt and reinstalled the app after adding the model.

An empty `Models/` directory still builds successfully, but the app will contain no selectable model.

## Installation or runtime failures

If signing fails, check the Team, Bundle Identifier, device connection, and Developer Mode. If a model fails to load, first verify the model files as described on this page. Use model files prepared with the iOS steps on this page.

For more issues, see [Troubleshooting](/troubleshooting).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.