roothide Developer: porting Theos tweaks to the roothide jailbreak

What kind of document this is

The repository description is minimal: document for tweak Developers, and the README title is update jailbreak apps/tweaks for roothide.

So this is a migration document, not a library and not a tool. It exists because roothide changed how jailbreak files are addressed, and every tweak that hardcoded the old rootless paths broke. The audience is narrow and specific: developers with existing tweak projects who want them to keep working.

The primary language is listed as Objective-C, which reflects the iOS context rather than a real codebase, and the repository holds documents rather than source. The top-level entries are README.md, roothide.md on the difference between roothide and legacy rootless, entitlements.md on entitlements and data sharing via files, interface.md on the SDK API and tools, vroot.md, filemirror.md, roothide.entitlements, plus a theos/ directory and images.

The topics list names jailbreak, jailbreak-detection-bypass, theos and theos-tweak. The licence is MIT, and the last push to the repository was on 2026-05-13 with no GitHub releases.

One naming note is worth making early, because searching for it is confusing. There is a separate roothide/theos repository, which is the toolchain fork, and this one is the documentation for it.

Installing the roothide fork of Theos

Step one is to install roothide/theos rather than upstream Theos, and the README gives the install command as a one-liner that pipes the install script into bash. The fork is described as always automatically synchronized and maintaining full compatibility with the original theos, which is the property that makes the approach viable: you are not running a diverged toolchain, you are running one that tracks upstream.

Step two is the build step, and it is where the first roothide-specific thing appears. For simple tweaks that do not use the file API to access jailbreak files, the README says to just run make package with THEOS_PACKAGE_SCHEME=roothide. That environment variable is the whole difference for a simple project: the package scheme selects how the resulting package is laid out and installed.

The README also points out that step three is only needed if you do use the file API, which is a useful indication of scope. Most tweaks that do not touch jailbreak files at all should need only the toolchain fork and the scheme variable.

Step six is the compatibility path for existing projects, and it is the part that matters most for an existing tweak. roothide/theos is compatible with building roothide packages from existing tweak projects that use rootless path macros, and there is a warning message to make sure you have read the document, which you can silence by defining the DISABLE_ROOTLESS_COMPAT_WARNING macro. So the old macros still work, the toolchain warns you that it is doing so, and you can turn the warning off once you have read the documentation.

For projects built with Xcode instead of Theos, the README points at a downloadable SDK, devkit.zip, published in the roothide/libroothide releases.

The jbroot API, and why paths were the problem

Step three is the code change, and it is small. You include the roothide header and use jbroot to resolve a jailbreak file path:

    #include <roothide.h>
    //then using roothide api to access jailbreak files
    const char* c_path = jbroot("/path/to/jb/file");
    NSString* objc_path = jbroot(@"/path/to/jb/file");
    std::string cpp_path = jbroot(std::string("/path/to/jb/file"));

The README is emphatic that the jbroot API can be used in C, C++, Objective-C and Swift, and that it is fully compatible with building rootful and rootless packages. That last point is the interesting one. The same call works whether the tweak is packaged rootful, rootless or roothide, which means you are not maintaining three branches of path handling.

The three overloads exist because the three languages pass strings differently. A C string literal becomes a const char*, an Objective-C string literal is an NSString, and a C++ call needs an explicit std::string. The function resolves the logical path to wherever the jailbreak root actually lives for the current scheme.

For Swift projects the README gives a specific recommendation: use a Swift bridging header file for #include <roothide.h> rather than import roothide in Swift source files, and it explains why, that this ensures the project stays compatible with building rootful and rootless. It links to Theos documentation on the Objective-C to Swift bridging mechanism. In practice this is the advice to follow, because the bridging header is the path the toolchain's own compatibility handling is built around.

Entitlements, and what they actually grant

Step four is adding entitlements to your executable or app so it works correctly with roothide, and the README gives the list:

    <key>platform-application</key>
    <true/>
    <key>com.apple.private.security.no-sandbox</key>
    <true/>
    <key>com.apple.private.security.storage.AppBundles</key>
    <true/>
    <key>com.apple.private.security.storage.AppDataContainers</key>
    <true/>

These are private Apple entitlements, not public ones. platform-application marks the binary as a platform application, which is the flag for an app that runs with elevated trust. com.apple.private.security.no-sandbox removes the sandbox restriction. The two storage keys grant access to other apps' bundle containers and data containers, which is what lets one tweak read another's data.

That last point is the reason this is a real design decision rather than boilerplate. On roothide, apps do not all share one filesystem root, so a tweak that needs to see another app's container has to ask for that capability explicitly. Without the entitlements, a tweak that worked on a stock rootless jailbreak will simply fail to find files it expects to exist.

The entitlements.md document in the repository covers the entitlements and data sharing via files in more detail, and the repository also ships a ready-made roothide.entitlements file, so the practical path is to look at that file and adapt it rather than assembling the list from scratch.

Where to read next, and who to ask

The README closes with three documents that cover the parts the quick guide only gestures at. The difference between roothide and legacy rootless, in roothide.md, is the conceptual one: it explains why the path model changed and why existing tweaks broke. Entitlements and data sharing via files, in entitlements.md, expands on the entitlement list above and on the container-sharing model. And roothide's SDK API and tools, in interface.md, documents the wider interface.

There is also vroot.md and filemirror.md, plus a theos/ directory in the repository, which suggests the fork's configuration is kept alongside the documentation.

Support is organised through several channels, which is normal for this ecosystem. The roothide developer account on Twitter is listed, and there is a roothide/theos-dev Discord server. Separately there is the roothide Discord server and the theos dev Discord server, and the theos one is where questions about Theos itself would go. The distinction matters because roothide-specific build problems and general Theos problems get answered by different people.

The MIT licence on the documentation is worth noting for a different reason. Because the documentation is permissively licensed, a downstream project can copy the entitlement list and the jbroot snippets into its own README without attribution obligations, which is presumably the point of licensing it that way.

Where this guide is the wrong resource

Three limits are structural. The first is that it assumes you already have a working tweak. Nothing here explains Theos packaging, the makefile layout, how a deb is assembled or how to write a tweak in the first place. If you are starting from an empty project, the Theos documentation is the place to begin, and this guide becomes relevant later.

The second is that it covers roothide, not the other direction. The compatibility path described is for projects moving to roothide that still use rootless path macros. If your tweak has to keep working across rootful, rootless and roothide simultaneously on devices the user chooses, the guide tells you about one target and leaves the matrix to you. The claim that jbroot is fully compatible with building rootful and rootless packages helps here, but you still have to build and test each variant.

The third is that this is a document with a short history and no release history. There are no GitHub releases, so there is no versioned changelog for the guidance, and the last push was on 2026-05-13. That matters more than it would for a library, because the thing being described, the roothide fork of Theos, changes underneath it. A guide that describes a moving toolchain without a version stamp has to be re-read against the current fork rather than pinned.

The alternative approach, and the difference is in what you port, is to convert the tweak's path handling by hand to whatever the target scheme expects instead of relying on the compatibility layer and the jbroot shim. The README's own framing points the other way, since it presents the compatibility macros and the jbroot API as the supported path, and for most tweaks the jbroot call is a smaller diff than rewriting every path. But a tweak that does something unusual with the jailbreak root, for example manipulating symlinks or relying on a specific directory layout, may find the shim does not cover it, and at that point reading interface.md becomes necessary.

Editorial conclusion

The guide suits a tweak developer who already has a working Theos project and needs it to run on roothide, since the work is concentrated in the toolchain fork, the jbroot calls and the entitlement list rather than in rewriting the tweak. It is the wrong tool if you are writing a tweak from scratch, because it assumes you already understand theos packaging, and it is the wrong tool if your project must keep supporting stock rootless jailbreaks without the roothide fork, since the guide covers only the roothide side of that compatibility problem. Verify first which package scheme your existing project builds, and note that the last push to the repository was on 2026-05-13 and there are no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. roothide/Developer on GitHub