Linux Terminal Agent

Linux Terminal Agent v1.2.89 is a Windows desktop AI-agent application backed by an Ubuntu WSL1 runtime. It combines a native PySide6 control center, a persistent shared Linux terminal, guarded Windows desktop/browser automation, file and document tools, voice input, and a multi-provider model pool.

Safety warning: the Linux runtime runs as root, and Windows drives mounted at /mnt/c, /mnt/d, and similar paths are the real host filesystems. A command that edits or deletes those files changes the Windows files directly. Review SECURITY.md before use.

Highlights

• Native Windows Control Center with chat and a shared persistent terminal.
• Ubuntu 24.04 on WSL1 with Windows-drive access and Windows executable interoperability.
• Provider pool support for Groq, Gemini Developer API, OpenAI API, ChatGPT/Codex CLI, OpenRouter, and Ollama where configured.
• Capability-aware attachments, screenshots, HTML artifacts, document generation, long-term memory, and multi-chat history.
• Optional Windows desktop control and managed Chrome/Edge browser control.
• Hybrid voice input: local wake detection with optional Groq command transcription and local fallback.
• Snapshot/restore utilities for the WSL distribution.
• Source and installer build paths with SHA-256 verification for downloaded Whisper/NSIS payloads.

Requirements

For normal source installation:

• Windows 10 or Windows 11
• Windows Subsystem for Linux (the installer keeps the dedicated distribution on WSL1)
• No separate Windows Python installation for the packaged installer; source mode verifies/installs Python 3.12 automatically when WinGet is available
• Internet access for the initial Ubuntu/Python/provider setup and any build assets not already cached

The packaged installer bundles the Windows Python application runtime.

Quick start

1. Extract or clone the repository to a normal Windows folder.
2. Open windows/ and run install.bat.
3. No Groq or other cloud API key is requested during installation.
4. After setup completes, run control-center.bat (or start.bat).
5. Open Settings and configure only the model providers you intend to use.
6. Select or drag a Windows project folder into the application to set the working directory.

See docs/INSTALLATION.md for first-install, upgrade, diagnostics, and uninstall details.

Common controls

Command	Purpose
windows/control-center.bat	Start the backend/helper and open the native Control Center
windows/start.bat	Start Linux Terminal Agent
windows/stop.bat	Stop the app, helper, GUI bridge, and WSL distro
windows/terminal.bat	Open an interactive root shell in the current console
windows/wsl-shell.bat	Open a WSL shell in Windows Terminal/PowerShell
windows/doctor.bat	Run installation/runtime diagnostics
windows/snapshot.bat	Export a WSL snapshot
windows/restore.bat	Restore a chosen WSL snapshot
windows/uninstall.bat	Unregister the dedicated WSL distribution and remove app data

Development

Create a Python environment, install development requirements, and run the test suite:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements-dev.txt
pytest -q

On Windows PowerShell, activate with .venv\Scripts\Activate.ps1 instead. The automated suite is platform-neutral/static enough to run outside Windows; real WSL1 and desktop-control behavior still requires a Windows test machine.

For installer builds, see docs/BUILDING.md.

Repository layout

guest/                 WSL-side Python service and agent runtime
windows/               Windows launchers, host helper, native UI, browser/voice helpers
packaging/             PyInstaller and NSIS packaging scripts
tests/                 Automated regression tests
docs/                  Architecture, installation, configuration, testing, and history
assets/                Application icon assets
tools/                 Build bootstrap scripts (downloaded NSIS is intentionally ignored)

Compatibility note

The public application name and packaged executables are now Linux Terminal Agent. Several internal WSL/runtime identifiers still use GroqVM so existing installations, data paths, and upgrade logic continue to work. The encrypted key-backup payload format also retains its historical internal format identifier so old backups remain importable; new exports use the .lta-keys extension and legacy .agentsmith-keys files are still accepted. See docs/COMPATIBILITY.md.

Security and privacy

API keys are stored by the local runtime rather than returned to the browser UI. Encrypted API-key backups use AES-256-GCM with a PBKDF2-SHA256 password-derived key. Desktop control and browser automation are local privileged capabilities and should be enabled only when needed. More detail is in SECURITY.md.

Documentation

• Installation
• Configuration
• Architecture
• Building
• Testing
• Compatibility / rename notes
• Release history
• Historical implementation notes

License

No open-source license was included in the source archive supplied for this project. Consequently, this repository does not grant reuse, redistribution, or modification rights beyond those provided by applicable law. Before publishing the repository for third-party reuse, choose and add the license you want.