Installation¶
This guide walks through installing TrueFidelity Desktop on Windows, macOS, and Linux. It covers system requirements, prerequisites, installation commands, license activation, updates, and troubleshooting.
System Requirements¶
Hardware Requirements¶
| Component | Minimum | Recommended |
|---|---|---|
| CPU | Quad-core 2.5 GHz | 6-8 cores, 3 GHz+ |
| Memory | 16 GB RAM | 32-64 GB RAM |
| Storage | 50 GB free (SSD) | 100+ GB NVMe SSD |
| Graphics | Any GPU with hardware acceleration | Dedicated GPU |
Software Requirements¶
| Requirement | Details |
|---|---|
| Operating System | Windows 10/11 (x64), macOS, Linux (x86_64) |
| Docker | Docker Desktop (Windows/macOS) or Docker Engine (Linux) |
| WSL2 | Required for Windows (with custom kernel from Nebula) |
| Permissions | Administrator/root privileges for installation |
| Network | Internet connection for installation and Docker image downloads |
| License | Valid license file or license server credentials |
Prerequisites¶
Before installing TrueFidelity Desktop, ensure the following prerequisites are met.
Docker Installation¶
Docker is required for ECU simulation features. TrueFidelity runs ECU containers using Docker.
Linux:
# Install Docker Engine
curl -fsSL https://get.docker.com | sh
# Add your user to the docker group
sudo usermod -aG docker $USER
# Log out and back in, then verify
docker --version
Windows:
- Download and install Docker Desktop for Windows
- During installation, ensure WSL2 backend is selected
- Start Docker Desktop and wait for it to initialize
- Verify installation:
docker --version
WSL2 Setup (Windows Only)¶
Windows requires WSL2 with a custom kernel from Nebula for full ECU simulation support.
# Install WSL2 (run PowerShell as Administrator)
wsl --install
After WSL2 is installed, contact Nebula support for the custom kernel installation instructions.
Linux Installation¶
Install Latest Release¶
Run the following command to install the latest version of TrueFidelity Desktop:
curl -fsSL https://github.com/NebulaTechSolutions/TrueFidelity/releases/latest/download/install-linux.sh | bash -s -- --yes
Installation Scope
With --yes, the installer defaults to user scope:
- User scope (default with
--yes): Installs to~/.local/share/truefidelitywith launcher in~/.local/bin - System scope: Installs to
/usr/share/truefidelitywith launcher in/usr/local/bin(requires sudo)
To install system-wide, run interactively (without --yes) and select "system", or use --scope system.
Install Specific Version¶
To install a specific version (e.g., v0.1.4):
curl -fsSL https://github.com/NebulaTechSolutions/TrueFidelity/releases/download/v0.1.4/install-linux.sh | bash -s -- --version v0.1.4 --yes
Installation Options¶
| Option | Description |
|---|---|
--version <tag> |
Install specific release version |
--scope <user\|system> |
Installation scope (default: user with --yes) |
--install-dir <path> |
Custom application directory |
--bin-name <name> |
Custom launcher name (default: truefidelity) |
--yes |
Skip confirmation prompts |
--uninstall |
Remove TrueFidelity installation |
What Gets Installed¶
The installer creates:
- Application:
~/.local/share/truefidelity/(user) or/usr/share/truefidelity/(system) - Launcher:
~/.local/bin/truefidelity(user) or/usr/local/bin/truefidelity(system) - Desktop Entry:
~/.local/share/applications/truefidelity.desktop(user) or/usr/share/applications/truefidelity.desktop(system) - User Directory:
~/truefidelity/- Contains user resources, templates, and documentation - tf-hwinfo: Hardware info tool for license generation (added to PATH)
Linux Troubleshooting¶
| Issue | Solution |
|---|---|
| Permission denied | Ensure you have write access to the installation directory |
| Docker not found | Install Docker Engine and add your user to the docker group |
| Command not found after install | Log out and back in, or run source ~/.bashrc |
| Missing dependencies | Install curl, tar, unzip via your package manager |
Windows Installation¶
Prerequisites Check¶
Before proceeding, ensure:
- Docker Desktop is installed and running
- WSL2 is installed (
wsl --install) - You have Administrator privileges for system-wide installation
Install Latest Release¶
Run the following commands in PowerShell:
# Set execution policy for this session
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
# Download and run the installer
Invoke-WebRequest -Uri "https://github.com/NebulaTechSolutions/TrueFidelity/releases/latest/download/install-windows.ps1" -OutFile "$env:TEMP\install-windows.ps1"
& "$env:TEMP\install-windows.ps1" -Yes
Installation Scope
- Administrator PowerShell: Installs system-wide
- Regular PowerShell: Installs per-user to
%LOCALAPPDATA%\TrueFidelity
Install Specific Version¶
To install a specific version (e.g., v0.1.4):
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
Invoke-WebRequest -Uri "https://github.com/NebulaTechSolutions/TrueFidelity/releases/download/v0.1.4/install-windows.ps1" -OutFile "$env:TEMP\install-windows.ps1"
& "$env:TEMP\install-windows.ps1" -Version v0.1.4 -Yes
What Gets Installed¶
The installer creates:
- Application:
C:\Program Files\TrueFidelity\(admin) or%LOCALAPPDATA%\TrueFidelity\(per-user) - Start Menu Shortcut: TrueFidelity shortcut in Start Menu
- PATH Entry: Application directory added to user PATH
- tf-hwinfo: Hardware info tool for license generation (installed to
%LOCALAPPDATA%\TrueFidelity\bin\)
Windows Troubleshooting¶
| Issue | Solution |
|---|---|
| Execution policy error | Run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass first |
| Docker not running | Start Docker Desktop and wait for it to fully initialize |
| WSL2 not installed | Run wsl --install in Administrator PowerShell and restart |
| Access denied | Run PowerShell as Administrator for system-wide installation |
| .NET Framework missing | Download from https://dotnet.microsoft.com/download/dotnet-framework |
macOS Installation¶
Prerequisites¶
Before installing on macOS, ensure Docker is installed:
- Download and install Docker Desktop for Mac
- Start Docker Desktop and wait for it to initialize
- Verify installation:
docker --version
Install Latest Release¶
Run the following command to install the latest version of TrueFidelity Desktop:
curl -fsSL https://github.com/NebulaTechSolutions/TrueFidelity/releases/latest/download/install-macos.sh | bash -s -- --yes
Installation Scope
With --yes, the installer defaults to system scope:
- System scope (default with
--yes): Installs to/Applicationswith launcher in/usr/local/bin(requires sudo) - User scope: Installs to
~/Applicationswith launcher in~/bin
To install per-user, run interactively (without --yes) and select "user", or use --scope user.
Install Specific Version¶
To install a specific version (e.g., v0.1.4):
curl -fsSL https://github.com/NebulaTechSolutions/TrueFidelity/releases/download/v0.1.4/install-macos.sh | bash -s -- --version v0.1.4 --yes
Installation Options¶
| Option | Description |
|---|---|
--version <tag> |
Install specific release version |
--scope <user\|system> |
Installation scope (default: system with --yes) |
--install-dir <path> |
Custom directory for the .app bundle |
--app-name <name> |
Custom application bundle name |
--bin-name <name> |
Custom launcher name (default: truefidelity) |
--yes |
Skip confirmation prompts |
What Gets Installed¶
The installer creates:
- Application Bundle:
/Applications/TrueFidelity.app(system) or~/Applications/TrueFidelity.app(user) - Launcher Script:
/usr/local/bin/truefidelity(system) or~/bin/truefidelity(user) - User Directory:
~/truefidelity/- Contains user resources, templates, and documentation - tf-hwinfo: Hardware info tool for license generation (added to PATH)
macOS Troubleshooting¶
| Issue | Solution |
|---|---|
| Permission denied | Use --scope user or run with sudo for system installation |
| Docker not found | Install Docker Desktop for Mac and ensure it's running |
| Command not found after install | Log out and back in, or run source ~/.zshrc |
| Gatekeeper blocks script | Run xattr -d com.apple.quarantine /tmp/install-macos.sh before executing |
Verification & Launch¶
After installation, verify the installation and launch TrueFidelity Desktop.
Verify Installation¶
truefidelity --version
This should display the installed version number.
Launch Application¶
From Command Line:
truefidelity
From Application Menu:
- Linux: Find TrueFidelity in your applications menu or launcher
- macOS: Find TrueFidelity in Launchpad or use Spotlight search
- Windows: Find TrueFidelity in the Start menu
First Launch Checklist¶
On first launch, verify the following:
- [ ] Docker Desktop is running (check system tray/menu bar)
- [ ] Splash screen appears and transitions to main window
- [ ] Approve any firewall prompts for local networking
- [ ] Complete license activation (see next section)
- [ ] Verify Help → About shows correct version
License Activation¶
TrueFidelity Desktop requires a valid license to operate. Two licensing options are available.
Node-Locked License¶
A node-locked license is tied to a specific machine based on hardware information.
- Launch TrueFidelity Desktop
- Open the License dialog when prompted
- Click Export Hardware Info to generate
hardware-info.json - Send the
hardware-info.jsonfile to support@nebula-automotive.com - Once you receive your signed license file, click Load License in the License dialog
- Select the license file to activate
Floating License (Server-Based)¶
A floating license allows multiple users to share licenses from a central server.
- Launch TrueFidelity Desktop
- Open the License dialog when prompted
- Select Floating License option
- Enter the License Server URL provided by your administrator
- Enter your API Key
- Click Validate to activate
License Support¶
For licensing questions or issues, contact:
- Email: support@nebula-automotive.com
- Subject: Include "License Request" or "License Issue" in the subject line
Updating TrueFidelity¶
Check Current Version¶
truefidelity --version
Update to Latest Version¶
Run the same installation command used for initial installation. The installer will update the existing installation while preserving your settings and projects.
Linux:
curl -fsSL https://github.com/NebulaTechSolutions/TrueFidelity/releases/latest/download/install-linux.sh | bash -s -- --yes
macOS:
curl -fsSL https://github.com/NebulaTechSolutions/TrueFidelity/releases/latest/download/install-macos.sh | bash -s -- --yes
Windows (PowerShell):
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
Invoke-WebRequest -Uri "https://github.com/NebulaTechSolutions/TrueFidelity/releases/latest/download/install-windows.ps1" -OutFile "$env:TEMP\install-windows.ps1"
& "$env:TEMP\install-windows.ps1" -Yes
Version Pinning
If you need to stay on a specific version for validation or certification purposes, use the specific version installation commands and avoid running the update commands.
Uninstalling¶
Linux¶
The installer includes an uninstall option:
curl -fsSL https://github.com/NebulaTechSolutions/TrueFidelity/releases/latest/download/install-linux.sh | bash -s -- --uninstall
Or remove manually:
# User installation
rm -rf ~/.local/share/truefidelity
rm ~/.local/bin/truefidelity
rm ~/.local/bin/tf-hwinfo
rm ~/.local/share/applications/truefidelity.desktop
# System installation (requires sudo)
sudo rm -rf /usr/share/truefidelity
sudo rm /usr/local/bin/truefidelity
sudo rm /usr/local/bin/tf-hwinfo
sudo rm /usr/share/applications/truefidelity.desktop
Windows¶
- Open Settings → Apps → Installed apps
- Find TrueFidelity and click Uninstall
Or remove manually:
# Per-user installation
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\TrueFidelity"
# Remove from PATH if added
# Check and edit Environment Variables in System Settings
macOS¶
Remove the application and launcher:
# System installation (requires sudo)
sudo rm -rf /Applications/TrueFidelity.app
sudo rm /usr/local/bin/truefidelity
sudo rm /usr/local/bin/tf-hwinfo
# User installation
rm -rf ~/Applications/TrueFidelity.app
rm ~/bin/truefidelity
rm ~/bin/tf-hwinfo
Clean Up User Data¶
After uninstalling, you may want to remove user configuration and data:
- Linux:
~/.config/truefidelityand~/truefidelity - macOS:
~/Library/Application Support/TrueFidelityand~/truefidelity - Windows:
%APPDATA%\TrueFidelity
Troubleshooting Common Issues¶
Docker Issues¶
| Symptom | Recommended Action |
|---|---|
| "Docker daemon not accessible" | Start Docker Desktop and wait for full initialization |
| ECUs fail to start | Increase Docker memory allocation to 8+ GB in Docker Desktop settings |
| Container resource errors | Run docker system prune -a to clean up unused resources |
Installation Issues¶
| Symptom | Recommended Action |
|---|---|
| Installer fails to download | Check internet connection and firewall settings |
| Permission denied | Use Administrator/root privileges or choose user-writable installation path |
| Command not found | Ensure installation directory is in your PATH, or log out and back in |
Application Issues¶
| Symptom | Recommended Action |
|---|---|
| App window stays blank | Launch with --disable-gpu flag, update graphics drivers |
| License activation fails | Check internet connection, verify license file/server details |
| Slow performance | Close unused panels, increase Docker resource allocation |
Collecting Diagnostic Logs¶
When reporting issues, include diagnostic logs:
- Launch TrueFidelity Desktop
- Reproduce the issue
- Access logs via Help → Show Logs (or check the locations below)
- Compress the logs directory and attach when contacting support
Log Locations:
- Linux:
~/.config/truefidelity/logs/ - macOS:
~/Library/Application Support/TrueFidelity/logs/or~/Library/Logs/TrueFidelity/ - Windows:
%APPDATA%\TrueFidelity\logs\
Next Steps¶
- Proceed to Quick Start for a hands-on tutorial
- Review UI Tour to understand the interface
- Explore System Design Workflow to build your first ECU network