Termux Extensions 2

It won't make you a professional programmer... but it'll make you feel like one.

---

TE2 is a local development workspace that runs the same project environment on Linux desktops and in Termux. Its framework launches isolated apps, owns shell and process orchestration, and provides shared filesystem, Git, search, state, proxy, console, and debugging services.

Code TE2 is the flagship workspace app: a Monaco-based editor with an Explorer, terminal surfaces, language tooling through code-server, diagnostics, drafts, diff/review flows, and stateful sidebar apps.

Architecture

TE2 is Rust-first. Python remains a support and app-backend language, not the framework authority.

te2
  -> Python bootstrap locator
  -> fingerprinted Rust framework binary
       -> Ferrous / Framework-Shells process orchestration
       -> Rust filesystem, Git, search, state, app, and proxy services
       -> Python runtime bridge for TE2 console and MCP
       -> per-app Python/Node/native workers

The supported Rust framework source lives under framework/.

Important roots:

• framework/rust/ — Rust framework workspace
• framework/bootstrap/bootstrap.py — cached build and launch bootstrap
• app/apps/ — built-in TE2 apps
• app/static/ and app/templates/ — framework-served assets
• app/te2_mcp/ and app/te2_console_runtime.py — runtime observability bridge
• ~/.local/share/te2/apps/ — user-local apps and proxy wrappers

Included Apps

• code_te2 — Code TE2, the primary workspace/editor app
• terminal — standalone Node PTY terminal with reconnect checkpoints
• file_explorer — standalone file browser
• archive_manager — archive browsing and extraction
• aria_downloader — aria2 download surface
• settings — framework settings and diagnostics
• als-rs — tracked ALS-RS proxy wrapper
• file_editor — older lightweight editor app retained separately from Code TE2

Integration depth varies by app. The app catalog is defined by the manifests under app/apps/*/manifest.json; there is no built-in codex_agent app.

Requirements

TE2's Python runtime requires Python 3.12 or newer. On the supported x86-64 Debian/Ubuntu Linux alpha, install build-essential before launching the standalone Terminal: its first launch compiles the locked node-pty module, then installs that module and the headless xterm modules into TE2's private data root for the current Node ABI. TE2's Linux Python dependency supplies the exact Node.js/npm runtime and matching headers, so a separate global Node.js install is not required. Archive Manager additionally needs the platform libarchive shared library.

The checked-in Code TE2 frontend, WBA backend, and shared browser assets are already built or vendored; ordinary runtime does not install npm dependency trees for them. The final archive-based Linux release will carry a prebuilt Electron distribution. A source, editable, or Git/pip install instead carries the small locked Electron source tree and builds it only when the user runs te2 desktop install or first launches te2-desktop.

A source or Git/pip install also needs Rust with Cargo because the launcher builds and caches the framework server. Building the optional desktop client from that install requires a glibc Linux x86-64 host plus Node.js 22.12 or newer and npm; its locked dependency and Electron downloads remain in the TE2 cache. Outside that explicit desktop build and the Terminal's private first-use runtime bootstrap, npm is development-only when regenerating checked-in artifacts. No global npm application package is required. Git is needed to clone the repository or resolve a Git dependency, but the running framework's Git implementation is Rust/libgit2 owned.

Some source integrations invoke external tools:

• aria2c enables the Aria Downloader worker;
• watchexec enables Code TE2's optional polling watcher; and
• C/C++ compiler commands enable Code TE2's direct C/C++ Run action.

For installed releases, each retained integration is supplied through the unified installer's validated Linux or Termux prerequisite manifest, or removed from the product. Users are not sent to repository construction scripts for dependency setup.

Code TE2 can use its built-in Monaco language workers without Code Server. VS Code extension-host integration uses Code TE2's confirmation-gated pinned private Code Server runtime; no global Code Server installation is supported. The managed Code Server Linux standalone bootstrap may require curl or wget when the user opts in. Its Termux path downloads the pinned package with Python and installs the exact package dependencies at that time.

The planned installed release uses one autodetecting install-te2 entrypoint with target-specific, checksummed tar/gzip archives. Detection checks Termux first, then supports an initial apt-based glibc Linux target. An explicit local payload or matching archive beside the installer supports offline application payload installation; otherwise the installer downloads the immutable release archive. Unsupported libc implementations, package managers, architectures, and platforms fail explicitly.

Linux installs beneath the canonical TE2 data root with a private Python venv and prebuilt Rust/Electron payloads; apt is limited to system prerequisites. Termux reuses its shared Python interpreter and apt-supplied dependencies without a venv, while TE2's own Python tree and Bionic server remain versioned beneath the canonical TE2 data root. Both targets share manifest verification, receipts, atomic current-release activation, upgrade/rollback, and removal.

Repository scripts are developer/release construction tooling and may build the public installer and target archives. They are not copied into an ordinary install or exposed as user installation entrypoints; users see them only in a cloned or editable source checkout.

Install And Run

For the supported x86-64 Debian/Ubuntu Linux alpha from PyPI:

sudo apt-get update
sudo apt-get install -y build-essential
python -m venv ~/.local/share/te2-alpha-venv
. ~/.local/share/te2-alpha-venv/bin/activate
python -m pip install "te2==0.2.338"
te2

build-essential supplies the compiler and make needed by the Terminal's first-use node-pty build. It is a system prerequisite, not part of TE2's Python environment.

For a source checkout:

python -m venv .venv
. .venv/bin/activate
python -m pip install -e .
te2

For a package install directly from Git:

python -m pip install "te2 @ git+https://github.com/mrsurge/termux-extensions-2.git"
te2

On supported Linux desktops, the same source/Git install can build and register the Electron client in the current Python environment:

te2 desktop install
te2-desktop

te2 desktop status, repair, and uninstall inspect, rebuild, or remove the fingerprinted user-local runtime and receipt-owned XDG integration. The build requires at least 3 GiB of free disk space; a matching validated runtime is reused without rebuilding.

Open http://127.0.0.1:8089. TE2 binds to localhost by default. Use te2 --broadcast all only when unrestricted network access is intentional. Prefer a narrower source or interface policy:

# Machine-readable names, addresses, prefixes, and networks.
te2 --list-interfaces

# Admit traffic whose destination is an address owned by this interface.
# This works for ordinary LAN adapters and /32 VPN adapters such as Tailscale.
te2 --broadcast tailscale0

# Admit only one client address or a client subnet.
te2 --broadcast 100.91.80.45
te2 --broadcast 100.64.0.0/10

# Mixed IPv4/IPv6 selectors are supported.
te2 --broadcast 192.168.1.0/24 fd7a:115c:a1e0::/48

Every filtered mode continues to admit loopback. The launcher resolves the selectors once, opens only the required IPv4/IPv6 wildcard listeners, and enforces the same policy before HTTP, SSE, raw WebSocket, or Socket.IO routing. Framework-owned subprocesses continue to receive a loopback TE_FRAMEWORK_URL, even when public listeners use wildcard addresses.

--host <exact-ip> remains an advanced bind override. A non-loopback exact host binds that address plus a private same-family loopback listener; wildcard host overrides allow all clients. Invalid selectors and interfaces without a usable IP address fail before the framework binds any socket.

The launcher builds an optimized release server by default; pass --debug only for an unoptimized development server. Cargo incremental artifacts live under $TE2_CACHE_HOME/framework/build/cargo-target, where $TE2_CACHE_HOME means the resolved canonical root described below. Final-binary publication is locked and atomic, and only the selected validated fingerprint is retained.

Launcher overrides use the canonical TE2_SERVER_* namespace: TE2_SERVER_HOST, TE2_SERVER_PORT, TE2_SERVER_CACHE_DIR, TE2_SERVER_BIN, TE2_SERVER_CARGO_MANIFEST, TE2_SERVER_DEBUG, TE2_SERVER_FORCE_BUILD, TE2_SERVER_NO_BUILD_CACHE, and TE2_SERVER_DISABLE_FERROUS_FRAMEWORK. Bootstrap-to-server values use the same namespace for bind hosts, internal host, network policy, project/app roots, and Cargo target selection. The private Python sidecar uses TE2_RUNTIME_BRIDGE_HOST, TE2_RUNTIME_BRIDGE_PORT, and TE2_RUNTIME_BRIDGE_URL. Experimental-name environment variables are not read as compatibility aliases. TE_PORT and TE_FRAMEWORK_URL remain the stable cross-component framework contracts.

TE2 path overrides (TE2_CACHE_HOME, TE2_DATA_HOME, TE2_CONFIG_HOME, and TE2_RUNTIME_HOME) name final TE2 roots. Without them, TE2 uses XDG bases when available, normal $HOME fallbacks for cache/data/config, and a protected runtime directory under $TMPDIR or Termux $PREFIX/tmp. Normal startup never uses an old root as a fallback for these migrated caches. Durable framework and Code TE2 store cutovers are tracked separately.

The first standalone Terminal launch installs its locked production Node dependencies under $TE2_DATA_HOME/node_runtime/terminal (normally ~/.local/share/te2/node_runtime/terminal after root resolution). The runtime is keyed by the lockfile, platform, architecture, and Node ABI, so Python package installs do not depend on a source-checkout node_modules tree.

Useful launcher commands:

te2 --build-only
te2 --debug
te2 --print-command
te2 --memory-profile "$HOME/.cache/te2-memory-profile"
te2 console list-workers
te2 migrate-legacy-roots          # write-free report
te2 migrate-legacy-roots --json   # write-free structured report

--memory-profile is an explicit desktop diagnostic mode. It requires a separately installed Heaptrack, uses an optimized symbolized Rust profile, and enables explicit Python and Node heap snapshots. It is not a production allocator mode. See the framework memory profiling guide before running it, especially when the active agent session is hosted by TE2.

Electron stores local launch policy separately at $TE2_CONFIG_HOME/desktop-local-framework.json. When that file is absent, Settings presents in-memory defaults and an unsaved te2 PATH detection; the Linux installer later seeds its exact private-venv and command paths. Source smokes may still use the higher-priority absolute TE2_DESKTOP_TE2_EXECUTABLE override. The versioned launch record owns the command, optional venv, broadcast selectors, port, and bounded environment overrides. An empty broadcast list stays loopback-only. Normal framework traffic remains on HTTP/Socket.IO/WebSocket/SSE. The bootstrap's --stdio-control mode is a desktop lifecycle channel: stdin accepts versioned NDJSON control requests, inherited file descriptor 3 returns structured responses/events, and stdout/stderr remain ordinary logs. Protocol v1 permits only graceful shutdown; it is not an arbitrary command-execution interface.

Legacy-root recovery is deliberately opt-in. After reviewing the dry-run, te2 migrate-legacy-roots --apply performs the versioned one-time migration only while the framework is stopped. The allowlisted legacy source is authoritative: matching canonical files are overwritten, while files that exist only in a canonical destination tree are retained. Unknown or externally owned content is reported and left untouched.

te2-rust is an alias for the same Rust launcher. scripts/run_framework.sh is a source-checkout helper that also invokes the Rust launcher directly.

Code TE2 does not use a system, PATH, NVM, or environment-selected code-server. Its Code Server mode always uses the pinned private runtime under $TE2_DATA_HOME/code_server/4.130.0 and routes process launch, VSIX/Open VSX management, builtin-extension discovery, and WBA nid extraction through that exact tree. The Languages & Extensions settings can switch the app to Monaco language web workers instead; doing so stops the private runtime and removes only its managed installation while preserving installed extensions.

Build Code TE2 Frontend

Code TE2 serves generated bundles from static/dist/. After changing its frontend source:

cd app/apps/code_te2
npm install
npm run typecheck
npm run build

The source entrypoints are main.ts for the host and monaco_editor/m_editor_app.ts for the editor. Generated bundles are not the source of truth.

App Model

Built-in and user-local apps share the same manifest model. An app may provide frontend assets, an app-worker shellspec, backend routes, semantic readiness, sidebar state, and proxy-wrapper configuration.

External applications do not need to be rewritten as TE2 internals. A thin wrapper under ~/.local/share/te2/apps/<app_id> can launch the real application through Framework-Shells and expose it through TE2's proxy surface. The wrapped application remains independently runnable; TE2 is its development harness, not a hidden product dependency.

Acknowledgements

TE2 depends on excellent independent open-source projects, including:

• Cefrium, which brings CEF to Android and powers TE2's Chromium-based Android client. Special thanks to its maintainer for the 0.7.1 iframe WebSocket and scheduling-latency fix.
• Electron, whose Chromium and Node.js runtime powers TE2's Linux desktop shell.

Repository Guidance

Technical Deep Dive (for a technical deep dive in how one makes a code/editor dev platform with a python script and have it perform as good as a VS-Clone)

GeckoView remains the primary Android client. The isolated android/cefrium application module evaluates the Cefrium CEF runtime without adding Chromium resources or native libraries to Gecko builds; see android/cefrium/README.md for its build and runtime contract.