credkellar/ios2termux repository overview

⁠iOS2Termux 📱➡️🐚

iOS to Termux with Gemini Carbon 4 Extended Thinking 🧠✨

Created by Darion Kellar · GitHub: credkellar/iOS-Termux⁠

⁠📖 What is this about?

This project started with a simple question: "How do I use Termux when my phone is an iPhone?" 📱

The honest answer has four parts:

1. 🚫 Native Termux on iOS does not exist. Termux is built for Android — its packages, its $PREFIX paths, its .deb files. An iPhone cannot install an APK, and there is no iOS build. Every "Termux for iPhone" claim is fake.
2. 🐚 iOS shells are real, but they are not Termux. iSH runs Alpine Linux in user mode (apk, not pkg). a-Shell and Blink Shell are useful cockpits/clients. None of them becomes Termux, and none can host sshd.
3. ✅ The winning route is SSH. Put real Termux on an Android device, start sshd (port 8022), and ssh in from iSH / Blink / Termius on the iPhone — same LAN, or Tailscale across networks. The iPhone is the cockpit; the Android device runs the real Termux.
4. ☁️ No Android handy? A cloud Linux box (Codespaces from the phone browser) with a pkg-style wrapper feels Termux-like, Termux commands translate to iSH equivalents for local work, and files move through iOS Files into Termux ~/storage/downloads.

iOS2Termux turns that answer into a tool: it classifies every route honestly, translates commands and paths both ways, plans the exact SSH / cloud / transfer setup phone-first, and HOLDs 🛑 the impossible or dangerous requests — decided by Gemini Carbon 4 Extended Thinking, gated by hard HOLD rules it can never override.

⁠🎯 What this does?

• 🗂️ Classifies 8 routes — impossible / shell-only / ssh-client / real-Termux / cloud / transfer-only — with an honest verdict for each
• 🔀 Translates 16 command pairs both ways — Termux <-> iOS (iSH): pkg install <-> apk add, clipboard, TTS, open, and more
• 🛣️ Translates paths both ways — ~/storage/downloads <-> iOS Files On My iPhone/Downloads, Termux $HOME/$PREFIX <-> iSH paths, and the ~/downloads private-folder warning ⚠️
• 🛡️ Rejects hostile shell input — ; rm -rf, $(...), backticks and pipes into sh are refused before they can become a command
• 🗺️ Plans any route — phone-first taps, the exact commands for each side, and generated files
• 📄 Generates setup-termux.sh — the one-time Android-side setup (openssh, storage, sshd, whoami, ip addr)
• 📄 Generates an ssh config snippet + a translate cheat-sheet (.md)
• 🧠 Decides with Gemini Carbon 4 Extended Thinking — MAP -> MODEL -> STRESS -> DECIDE, extended tier (32768 budget) by default
• 🛑 Enforces 8 HOLD gates — impossible claims, public sshd with no auth, secrets in command history, rm -rf on shared storage, unextracted archives, the private-downloads trap
• 🔗 Keeps a hash-chained blackbox log of plans and verdicts, tamper-evident
• 🤖 Registers freeai advisor seats by name only — including the Muse seat (MODEL_API_KEY, Meta, pay-as-you-go) — advisors can recommend, they can never override a HOLD

⁠🔧 How this works?

⁠The truth table 📋

⁠The flow 🌊

1. 📱 You pick a route (default: SSH into real Termux)
2. 🧠 Carbon 4 runs MAP -> MODEL -> STRESS -> DECIDE; the HOLD gates run inside STRESS
3. 🛑 Any gate tripped = HOLD, printed with its reason — Carbon 4 can never loosen it
4. 🗺️ Clear plans emit phone steps + exact commands + generated files
5. 🔗 The blackbox logs the plan and the verdict

⁠🛑 The HOLD gates

⁠🧠 Gemini Carbon 4 Extended Thinking

• Engine: gemini-2.5-pro · Model ID: google/gemini-carbon-4-extended-pro-thinking
• Thinking tiers: standard 2048 · deep 8192 · extended 32768 (default)
• Phases: MAP (name the action + route) -> MODEL (require the facts) -> STRESS (worst cases + the HOLD gates) -> DECIDE (strictest verdict: HOLD / PROCEED)
• Offline structure is authoritative. A live polish (only when GEMINI_API_KEY is present — detected by name only, value never read) can only tighten a verdict, never loosen one.
• Negative controls, locked in by tests: a plain pkg install python translation must NOT escalate to HOLD ✅ · a local iSH ls / python3 script.py must NOT be held just because Termux is absent ✅ · a single benign transfer to ~/storage/downloads must PROCEED ✅

⁠🏗️ Architecture

flowchart TD
    A["📱 iPhone<br/>iSH / Blink / Safari"] --> B["main.py<br/>ONE interface"]
    B --> C["🗺️ planner.py<br/>route → plan"]
    C --> D["🧠 carbon4.py + brains.py<br/>Carbon 4 decides · gates HOLD"]
    D -->|HOLD 🛑| E["exit 2<br/>reason printed"]
    D -->|clear ✅| F["📋 phone steps + commands + files"]
    C --> G["🗂️ routes.py<br/>8 routes, honestly classified"]
    C --> H["🔀 translate.py<br/>16 pairs + paths, injection-proof"]
    F --> I["🐧 REAL Termux on Android<br/>sshd :8022"]
    F --> J["☁️ Cloud-Termux<br/>Codespaces + pkg wrapper"]
    B --> K["🔗 blackbox.py<br/>hash-chained log"]
    B --> L["🤖 freeai.py<br/>advisor seats, names only"]

⁠😎 Why is this cool?

Because it tells the truth and then makes the truth useful. Most "Termux on iPhone" content is either a lie or a dead end. This project draws the exact line between impossible, shell-only, and actually-works — then automates the part that works, end to end, from a phone, with an extended-thinking decider that is forbidden from overriding its own safety gates. 📱✨

⁠🔟 10 reasons why this is cool

1. 🧭 Honesty as a feature — the impossible routes are labelled impossible, in code, with gates that enforce it
2. ⭐ One recommended route — SSH into real Termux: every pkg, path and tool, from your iPhone
3. 🔀 A real translator — 16 command pairs + path translation, both directions, not a blog-post table
4. ⚠️ The downloads trap is encoded — ~/downloads (private) vs ~/storage/downloads (shared) is a gate, a warning, and a test
5. 🧠 Extended thinking, on a leash — Carbon 4 decides with a 32768 budget, and a HOLD still always wins
6. ✅ Negative controls — tests prove benign work (translations, local iSH, one file transfer) is NOT over-held
7. 📄 Files that generate themselves — setup-termux.sh, the ssh config, and the cheat-sheet come out of the planner
8. 🛡️ Injection-proof by design — a hostile command can never smuggle shell syntax into a plan
9. 0️⃣ Zero dependencies — pure Python 3.12 stdlib; runs anywhere Python runs, including inside its own Docker image
10. 🔗 Tamper-evident memory — plans and verdicts are hash-chained in the blackbox

⁠🐳 Run it

docker pull credkellar/ios2termux:latest
docker run --rm credkellar/ios2termux
# 🧪 expect: CHECKS 48/48 PASS · VERDICT: PROCEED

From source:

git clone https://github.com/credkellar/iOS-Termux.git
cd iOS-Termux
python3 main.py                                    # self-check
python3 main.py --plan                             # the recommended SSH plan
python3 main.py --translate "pkg install python" --to ios

⁠📋 The numbers

• 🧪 43 tests passed · CHECKS 48/48 · 0️⃣ zero dependencies (pure Python 3.12 stdlib)
• 🛂 8 routes classified · 🔀 16 command translations + 5 path translations, both directions
• 🛑 8 HOLD gates · 🧠 Gemini Carbon 4 Extended Thinking decides (32768 extended budget) and can never override a HOLD
• 📱 Phone = cockpit · 🤖 Android Termux = engine · 🔐 SSH port 8022 = the bridge