Kodrix IDE Documentation

Welcome to the official documentation. This guide covers the internal architecture, how to use runtimes, web frameworks, Git, crash reporting, and how to troubleshoot common errors on Android.

1. Architecture & File System

Kodrix emulates a standard Linux environment on Android using a custom virtualized filesystem inside its sandboxed app directory at /data/data/com.kodrix.zohaib/files/.

Directory	Purpose
/usr/bin/	Primary execution path. Active wrappers for node, git, etc. When you type node, this is where it resolves.
/usr/bin_safe/	Recovery directory. Contains static wrappers pointing strictly to bundled tools. Used only during Safe Mode.
/usr/lib/	Shared libraries (.so files) required by downloaded runtimes (e.g., libffi.so, libz.so.1).
/npm_pkg/	Global NPM directory. npm install -g puts packages here to bypass Android permission restrictions.
/runtimes/	Storage for downloaded toolchain versions from the Marketplace.

2. Runtimes & The Marketplace

The built-in Marketplace lets you download and hot-swap entire toolchains without reinstalling the app.

Bundled vs Downloaded Runtimes

• Bundled: Kodrix ships with pre-compiled, stable tools (Node.js v25, Git v2.34.0) guaranteed to work on Android's Bionic libc.
• Downloaded: You can fetch newer versions from the Marketplace. Kodrix dynamically updates /usr/bin/ wrappers to point to the new version.

Beta Mode

Experimental features and runtimes are hidden by default. To access them:

1. Open the IDE and go to the Settings tab.
2. Scroll to the Developer section.
3. Toggle Beta Mode ON.

The Runtimes tab will now appear in the Marketplace. Your preference is saved across restarts.

3. Working with Web Frameworks

Kodrix fully supports React, Vue, Svelte, Next.js, and Vite. Use the terminal to scaffold and run projects.

React + Vite

npx create-vite@latest my-app --template react
cd my-app
npm install
npm run dev

Next.js

npx create-next-app@latest my-app
cd my-app
npm run dev

Once the server starts, open Kodrix's Browser tab and navigate to http://localhost:5173 (or whichever port is shown).

Python 3

Python 3 runs fully on-device with no additional setup.

python3 --version
python3 script.py

Install packages using pip:

pip3 install requests numpy flask

Flask (Python Web Server)

pip3 install flask

# app.py
from flask import Flask
app = Flask(__name__)

@app.route('/')
def home():
    return 'Hello from Kodrix!'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

python3 app.py

Once Flask starts, open Kodrix's Browser tab and navigate to http://localhost:5000.

Framework	Status	Notes
React + Vite	✅ Working	Use @vitejs/plugin-react
Express / Node.js	✅ Working	Full support
Vue + Vite	✅ Working	Pure JS build
Svelte + Vite	✅ Working	Pure JS build
Next.js	✅ Working	Webpack mode only — no Turbopack
Python 3	✅ Working	Full runtime environment support

4. Source Control (Git)

Git v2.34.0 is bundled and available immediately in the terminal. No additional setup is needed.

git init
git add .
git commit -m "Initial commit"
git push

Authentication

Browser-based OAuth may fail inside the Android sandbox. Use GitHub Personal Access Tokens (PAT) instead:

git clone https://<YOUR_TOKEN>@github.com/username/repo.git

Generate a token at GitHub → Settings → Developer settings → Personal access tokens.

5. Developer Settings

Found in Settings → Developer, these tools are for advanced users and IDE developers.

Beta Mode Toggle

Unlocks experimental features and the Runtimes tab in the Marketplace. See Section 2.

Force Test Crash

A red Force Test Crash button is available below the Beta Mode toggle. When tapped:

• The app immediately crashes with the log message "App is forced crashed".
• This message appears verbatim in Firebase Crashlytics, making deliberate test crashes instantly distinguishable from real crashes.
• Re-open the app after tapping — Crashlytics sends the report on the next launch.

6. Crash Reporting (Firebase Crashlytics)

Kodrix IDE uses Firebase Crashlytics to automatically capture all crashes — Java, Kotlin, and native NDK.

• Dashboard: console.firebase.google.com → Project kodrixide → Crashlytics
• Reports appear within 2–5 minutes of the crash occurring.
• Crashes are uploaded on the next app launch after they occur.
• Active for both debug and release builds.

7. Troubleshooting & Common Errors

Error: CANNOT LINK EXECUTABLE: library "libffi.so" not found

Cause: You downloaded an experimental Node.js version (e.g., v26.2.0) that depends on a shared library missing from Android's core system.

Fix: Open the Marketplace and activate the Bundled (v25) or a stable LTS version instead.

Error: CANNOT LINK EXECUTABLE: library "libz.so.1" not found

Cause: A downloaded Git binary is failing to link with the bundled zlib.

Fix: Switch your Git version back to v2.34.0 (Bundled) via the Marketplace.

Error: Exec format error on Node.js

Cause: CPU architecture mismatch — e.g., running an ARM binary on an x86_64 emulator.

Fix: Enable Beta Mode, open the Marketplace Runtimes tab, and download the version matching your device architecture.

Error: Permission denied when running a script

Cause: The file lacks execution permissions (Android enforces this strictly).

Fix: Run chmod +x your_script.sh before executing.

Emergency Recovery: Safe Mode

If a broken runtime crashes the terminal instantly on open (preventing you from fixing it):

1. Open the IDE Settings tab.
2. Scroll to Environment and enable Safe Mode.
3. Restart the Terminal session. It now uses /usr/bin_safe/, ignoring all downloaded runtimes.
4. Open the Marketplace and switch your active runtime to a Bundled version.
5. Return to Settings and turn Safe Mode OFF.