mirror of
https://github.com/StikDebug/StikDebug.git
synced 2026-10-16 12:30:29 +00:00
5ba55e7bb8
The tunnel reconnect in the previous commit only fires while StikDebug is
actually executing. In the real handoff scenario the user has switched to the
JIT-enabled app, so StikDebug is backgrounded — and upstream lets iOS suspend
it, which means the path-change notification is never delivered and the
tunnel stays dropped.
Two upstream behaviours cause that suspension:
- Keep-alive only ran if the user had the "Silent Audio"/"Background Location"
toggles on. DebugKeepAliveLease now takes forced holds (force: true) that
bypass those toggles for the duration of a debug session, released when the
session ends. Both managers keep separate forced/unforced counters.
- The background-task expiration handler called invalidate(), tearing down
audio and location the moment the ~30s assertion elapsed. It now renews the
assertion (re-checking isActive) while silent audio sustains execution.
Also play an inaudible non-zero signal (~-80 dBFS, DC-free) instead of digital
silence, which some iOS versions treat as idle and reclaim. SettingsView calls
refreshFromSettings() rather than stop(), so toggling the setting off no longer
kills a forced session hold.
This is the minimal slice of the PR's keep-alive work that the cellular
reconnect depends on. Drop this commit for a foreground-only cellular fix.
Ported from StephenDev0/StikDebug#432 commit 656ec6d (keep-alive slice).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
160 lines
7.1 KiB
Markdown
160 lines
7.1 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 LocalDevVPN is on. Any network works (Wi-Fi **or** cellular); the tunnel rides the VPN, so cellular-only is supported. It may also be a pairing file issue.
|
||
- Session drops after switching to another app → Keep the background keep-alive enabled (Settings → Background Keep-Alive). While a JIT/debug session is active, StikDebug plays inaudible audio and holds a background assertion so the session survives being switched out of the app instead of timing out.
|
||
- 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.).
|
||
|
||
## 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.
|