Installing RoleThread Lite

RoleThread Lite can run from a normal source checkout or from the Windows setup installer. The setup installer is the easier Windows beta path. The manual path is still the most transparent workflow for developers, technical users, Linux, and macOS.

Choose An Install Method

Use the Windows setup installer if you want RoleThread Lite to behave like a normal desktop app with a Start Menu shortcut, bundled runtime, and managed Windows Edge app window.

Use the manual source workflow if you want full visibility into the Python environment, dependency installation, launch command, and repository files. On Linux and macOS, that source workflow can still use LitLaunch for managed local runtime behavior, diagnostics, runtime event logging, and support artifacts.

RoleThread Lite V1 is tested on Python 3.14.5 with the Streamlit 1.57.x runtime line. The source requirements keep Streamlit on that line during the V1 stabilization window.

Windows Setup Installer

The Windows setup executable is a beta convenience path. It packages a tested release snapshot and does not clone from Git or require a local Python install. It is expected to keep improving as installer testing continues.

1. Download the latest RoleThread Lite setup executable from GitHub Releases.
2. Run the setup executable and accept the Windows UAC prompt.
3. Choose whether to create a Desktop shortcut.
4. Finish setup and launch RoleThread Lite from the installer, Start Menu, or Desktop shortcut.

Installed RoleThread Lite starts like a normal local app. The packaged launcher uses LitLaunch behind the scenes, keeps the app bound to your own computer at 127.0.0.1, and opens RoleThread in a local Edge app-style window. Users do not choose a runtime mode during setup.

On some Windows systems, the installer may appear behind other windows after the UAC prompt. If setup does not appear immediately, minimize other windows or check the taskbar for the RoleThread Lite installer.

The installed app stores user data separately from installed program files:

Program files:
C:\Program Files\RoleThread Lite\

App data:
%LOCALAPPDATA%\RoleThread\

Workspace:
%USERPROFILE%\RoleThread\

Windows Manual Install

Manual Windows setup is useful when working from source.

py -3.14 -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
streamlit run app.py

For the Windows app-window launch path:

python -m litlaunch.cli run --profile rolethread-webapp

This uses the same LitLaunch profile model as the installed app. LitLaunch starts the local app runtime, binds it to 127.0.0.1, and opens the Edge app window.

Linux Manual Install

Linux uses the source/manual workflow for V1 and is a primary supported platform for that workflow.

python3.14 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
streamlit run app.py

For LitLaunch-managed browser-mode runtime, diagnostics, and support artifacts:

python -m litlaunch.cli run --profile rolethread-browser
python -m litlaunch report --profile rolethread-webapp --force

The Windows Edge app-window profile is not the Linux V1 packaged path. Use normal browser mode, the LitLaunch browser profile, or a browser app shortcut if your browser supports it.

macOS Manual Install

macOS is beta/manual for V1 because direct maintainer testing is limited. The source architecture and LitLaunch workflows are intended to work where the Python dependencies are available.

python3.14 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
streamlit run app.py

For LitLaunch-managed browser-mode runtime, diagnostics, and support artifacts:

python -m litlaunch.cli run --profile rolethread-browser
python -m litlaunch report --profile rolethread-webapp --force

The Windows Edge app-window profile is not the macOS V1 packaged path. Use normal browser mode, the LitLaunch browser profile, or a browser app shortcut if your browser supports it.

Uninstalling On Windows

The normal Windows uninstall path removes installed app/runtime files, shortcuts, and the uninstall entry. It preserves local RoleThread user data.

Use one of these uninstall paths:

• Start Menu > RoleThread Lite > RoleThread Uninstaller
• Windows Settings > Apps > Installed apps > RoleThread Lite > Uninstall
• Control Panel > Programs and Features > RoleThread Lite > Uninstall

Default uninstall preserves:

%LOCALAPPDATA%\RoleThread\
%USERPROFILE%\RoleThread\

The uninstaller can optionally remove local RoleThread user data. That destructive option deletes local database/app state, preferences, logs, cache, training data, imports, exports, backups, and workspace data under the two RoleThread-owned roots above.

Cloud backup copies and external sync folders outside the local RoleThread folders are preserved. Delete those manually from the cloud provider or sync folder if desired.

Close RoleThread Lite before uninstalling. The uninstaller checks for RoleThreadLauncher.exe and asks you to close the app instead of broadly terminating Python, Edge, Streamlit, or browser processes.