mirror of
https://github.com/StikDebug/StikDebug.git
synced 2026-10-16 04:20:30 +00:00
184 lines
8.2 KiB
Markdown
184 lines
8.2 KiB
Markdown
<div align="center">
|
||
<img width="217" height="217" src="/assets/StikDebug.png" alt="Logo">
|
||
</div>
|
||
|
||
<div align="center">
|
||
<h1><b>StikDebug</b></h1>
|
||
<p><i>An on-device debugger/JIT enabler for iOS versions 17.4+ powered by <a href="https://github.com/jkcoxson/idevice">idevice</a>.</i></p>
|
||
</div>
|
||
|
||
<h6 align="center">
|
||
<a href="https://discord.gg/ZnNcrRT3M8">
|
||
<img src="https://img.shields.io/badge/Discord-join%20us-7289DA?logo=discord&logoColor=white&style=for-the-badge&labelColor=23272A" />
|
||
</a>
|
||
<a href="https://github.com/StikDebug/StikDebug/blob/main/LICENSE">
|
||
<img src="https://img.shields.io/github/license/StikDebug/StikDebug?label=License&color=5865F2&style=for-the-badge&labelColor=23272A" />
|
||
</a>
|
||
<a href="https://github.com/StikDebug/StikDebug/stargazers">
|
||
<img src="https://img.shields.io/github/stars/StikDebug/StikDebug?label=Stars&color=FEE75C&style=for-the-badge&labelColor=23272A" />
|
||
</a>
|
||
<a href="https://github.com/StikDebug/StikDebug/releases">
|
||
<img src="https://img.shields.io/github/v/release/StikDebug/StikDebug?label=Latest&color=00BFFF&style=for-the-badge&labelColor=23272A" />
|
||
</a>
|
||
<br />
|
||
</h6>
|
||
|
||
## Features
|
||
- **JIT:** Enable Just In Time compilation for sideloaded apps that have the `get-task-allow` entitlement.
|
||
- **App Launching:** Launch every app installed on your device.
|
||
- **Console:** Live app and system logs.
|
||
- **Scripts:** Manage automation scripts (mainly used for iOS 26 JIT).
|
||
- **App Expiry:** See when apps will expire and install/remove profiles.
|
||
- **Device Info:** View detailed device metadata.
|
||
- **Processes:** Inspect running apps/processes and terminate them.
|
||
- **Location Simulator:** Simulate the GPS location of your device.
|
||
|
||
## Download
|
||
> [!NOTE]
|
||
> **Notice:** StikDebug is no longer available on the App Store. Please use the official download methods below.
|
||
|
||
<h3 align="center">
|
||
<a href="https://altdirect.app/?url=https://stikdebug.xyz/index.json" target="_blank"><img src="https://altdirect.app/assets/png/AltSource_Blue.png" alt="Add AltSource" width="200"></a>
|
||
|
||
<a href="https://github.com/StikDebug/StikDebug/releases/download/3.1.9/StikDebug-3.1.9.ipa" target="_blank"><img src="https://altdirect.app/assets/png/Download_Blue.png" alt="Download .ipa" width="200"></a>
|
||
</h3>
|
||
|
||
## Compatibility
|
||
|
||
| iOS Version | Status | Notes |
|
||
|--------------------------|----------------------|-----------------------------------------------------------------------|
|
||
| 1.0 – 17.3.X | Not supported | Uses Different Connection Protocols |
|
||
| 17.4 – 18.x | Fully supported | Stable |
|
||
| 26.0+ | Supported | Limited App Availability (Developers need to update their apps to work.) |
|
||
|
||
## How to Enable JIT
|
||
|
||
StikDebug enables **JIT** for sideloaded apps on iOS 17.4+ without needing a computer after the initial pairing setup.
|
||
|
||
### Requirements
|
||
- StikDebug installed (via AltSource, direct .ipa, or self-built)
|
||
- A valid **pairing file** (.plist / .mobiledevicepairing) for your device
|
||
- SideStore / AltStore / similar sideload tool (for app refreshing)
|
||
- A loopback VPN such as [LocalDevVPN](https://apps.apple.com/us/app/localdevvpn/id6755608044)
|
||
|
||
### Steps
|
||
1. **Obtain a pairing file**
|
||
- Detailed guide: [Pairing File Instructions](https://github.com/StikDebug/StikDebug-Guide/blob/main/pairing_file.md) (or ask in Discord).
|
||
|
||
2. **Set up VPN**
|
||
- Launch LocalDevVPN and enable the VPN.
|
||
|
||
4. **Enable JIT for an app**
|
||
- Launch StikDebug and tapp the `Enable JIT` button.
|
||
- Select your sideloaded app from the list in StikDebug.
|
||
|
||
**Troubleshooting**
|
||
- "Connection dropped" or loopback errors → Check iOS version compatibility / beta warnings.
|
||
- Heartbeat errors → Ensure that the VPN is on and that you are connecected to Wi-Fi. It may be a pairing file issue.
|
||
- Pairing file issues → Replace file with device unlocked & trusted.
|
||
- Still stuck? Join the [Discord](https://discord.gg/ZnNcrRT3M8) with logs/screenshots.
|
||
|
||
<!--
|
||
## Screenshots
|
||
|
||
<div align="center">
|
||
<img src="screenshots/pairing-import.png" width="320" alt="Pairing file import screen">
|
||
<img src="screenshots/app-list.png" width="320" alt="Sideloaded apps list">
|
||
<img src="screenshots/jit-enabled.png" width="320" alt="JIT successfully enabled">
|
||
<img src="screenshots/processes.png" width="320" alt="Process management tab">
|
||
</div>
|
||
|
||
(Add images to a /screenshots/ folder in the repo and uncomment when ready.)
|
||
-->
|
||
|
||
## Building from Source
|
||
|
||
> [!IMPORTANT]
|
||
> **Integrating StikDebug or StikJIT into your own project?**
|
||
> See the [StikJIT Integration Guide](https://github.com/StikDebug/StikJIT/blob/main/INTEGRATION.md) for integration instructions.
|
||
|
||
### Requirements
|
||
- macOS (latest recommended)
|
||
- Xcode 16+ (Xcode 26+ preferred for iOS 26+ support)
|
||
- iOS device on iOS 17.4+ (for testing)
|
||
- Git
|
||
- Basic Xcode/Swift knowledge
|
||
|
||
### Steps
|
||
1. **Clone the repo**
|
||
```bash
|
||
git clone https://github.com/StikDebug/StikDebug.git
|
||
cd StikDebug
|
||
```
|
||
|
||
2. **Open in Xcode**
|
||
- Launch Xcode
|
||
- Open `StikDebug.xcodeproj`
|
||
|
||
3. **Configure signing**
|
||
- Select the **StikDebug** target
|
||
- Go to **Signing & Capabilities**
|
||
- Sign in with your Apple ID (free or paid developer account)
|
||
- Set a unique **Bundle Identifier** (e.g., `com.yourname.StikDebug`)
|
||
|
||
4. **Build & install**
|
||
- Select your connected device
|
||
- Press **Cmd + R** (or Product → Run)
|
||
- Trust the certificate on device: Settings → General → VPN & Device Management
|
||
|
||
After install, follow the JIT setup steps above (pairing import, etc.).
|
||
|
||
### Native library and iOS 27 developer image
|
||
|
||
Before building from source, run `python3 scripts/prepare_idevice.py`. It downloads
|
||
the official idevice 0.1.68 iOS archive, verifies its pinned SHA-256 checksum, and
|
||
installs the matching library and header. The larger native library is downloaded
|
||
instead of being stored in Git.
|
||
|
||
The IPA workflow also runs `python3 scripts/prepare_cryptex_ddi.py --output build/BundledCryptexDDI`
|
||
and copies that directory to the app bundle root. For a direct Xcode build, prepare
|
||
the same directory and include it as a folder resource named `BundledCryptexDDI`.
|
||
All four payloads are checked against the manifest's SHA-384 digests; the download
|
||
is pinned to an immutable revision of the DeveloperDiskImage repository.
|
||
|
||
On iOS 27 with the Cryptex service available, StikDebug personalizes and mounts
|
||
this generic image. It does not require the legacy manifest to list the device's
|
||
chip/board identity. Other systems retain the existing personalized mounting path.
|
||
|
||
The Cryptex implementation was tested on `iPhone19,2`, iOS 27.0: after confirming
|
||
that no developer image was mounted, StikDebug mounted it independently and
|
||
enabled JIT for MeloNX. The existing game reached its title screen at about
|
||
60 FPS. Other models and older iOS versions still need regression testing.
|
||
|
||
Run `swift test` to check generic image validation, including all four payload
|
||
digests, missing files, and manifest paths outside the verified directory.
|
||
|
||
## Contributing
|
||
|
||
Thank you for your interest in contributing to this project. Contributions of all kinds are welcome.
|
||
|
||
### Reporting Bugs
|
||
If you discover a bug, please open an issue and include:
|
||
- A clear and descriptive title
|
||
- Steps to reproduce the issue
|
||
- Expected behavior vs. actual behavior
|
||
- Relevant logs, screenshots, or environment details (iOS version, device model, etc.)
|
||
|
||
### Suggesting Features
|
||
To propose a new feature, open a feature request issue and provide:
|
||
- A clear description of the feature
|
||
- The problem it solves or the use case it addresses
|
||
- Any relevant examples or implementation ideas
|
||
|
||
### Code Contributions (Best Practices)
|
||
- Follow normal Swift and SwiftUI style.
|
||
- Write clear and easy to understand code.
|
||
- Keep your changes consistent with how the project is already set up.
|
||
- Make sure everything builds and works without errors.
|
||
|
||
We appreciate your time and effort in helping improve this project.
|
||
|
||
## Code Help
|
||
[](https://deepwiki.com/StikDebug/stikdebug)
|
||
## License
|
||
StikDebug is licensed under **AGPL-3.0**. See [`LICENSE`](LICENSE) for details.
|