================================================================================
TNT LIGHTWEIGHT CLIENT - INSTALLATION INSTRUCTIONS
================================================================================

WHAT'S IN THIS FOLDER:
  - All files needed to run the TNT Client
  - Nothing else - ready to copy and deploy!

================================================================================
QUICK INSTALL
================================================================================

STEP 1: Copy this entire folder to your target machine
  - Copy the whole "TNT_Client" folder
  - Place it anywhere (e.g., C:\TNT_Client or /opt/TNT_Client)

STEP 2: Run the installer

  WINDOWS:
    1. Right-click on install.bat
    2. Select "Run as Administrator"
    3. Wait for installation to complete

  LINUX/MAC:
    1. Open terminal in this folder
    2. Run: chmod +x install.sh
    3. Run: ./install.sh
    4. Wait for installation to complete

STEP 3: Start the client

  WINDOWS:
    - Double-click start_client.bat
    (or right-click and "Run as Administrator" for better scanning)

  LINUX/MAC:
    - Run: ./start_client.sh
    (or use sudo for better scanning capabilities)

STEP 4: Configure in browser
    1. Open web browser
    2. Go to: http://127.0.0.1:5100
    3. Click "Setup"
    4. Fill in:
       - Server URL: http://your-tnt-server:5000
       - Username: your-username
       - Password: your-password
       - Client Name: A friendly name for this machine
       - Location: Where this machine is located
    5. Click "Connect & Register"

DONE! Your client is now connected and ready to scan.

================================================================================
SYSTEM REQUIREMENTS
================================================================================

- Python 3.8 or later
- 1GB RAM minimum
- 5GB disk space
- Network connection to TNT server
- Administrator/sudo access (for network scanning)

WINDOWS:
  - Windows 10/11
  - Built-in tools (arp, ping) - no extras needed
  - Optional: nmap for advanced scanning

LINUX:
  - Any modern distribution
  - Recommended: apt-get install arp-scan nmap

MAC:
  - macOS 10.15 or later
  - Recommended: brew install nmap

================================================================================
WHAT GETS CREATED
================================================================================

After installation:
  - venv/ folder (Python virtual environment)
  - client_config.ini (your configuration)
  - client_encryption.key (encryption key for API key storage)
  - scan_results/ folder (local scan backups)
  - tnt_client.log (application log file)
  - start_client.bat or start_client.sh (startup script)

================================================================================
RUNNING SCANS
================================================================================

1. Open browser to http://127.0.0.1:5100
2. Go to "Scan" page
3. Choose scan type:
   - Network Discovery: Scan entire local network
   - Device Scan: Scan specific IP address
4. Click "Start Scan"
5. Results automatically upload to server

================================================================================
TROUBLESHOOTING
================================================================================

CLIENT WON'T START:
  - Check Python is installed: python --version
  - Run installer again
  - Check tnt_client.log for errors

CAN'T CONNECT TO SERVER:
  - Verify server URL is correct
  - Check firewall isn't blocking port 5000
  - Ping the server to test connectivity
  - Check server is running

SCANS FAIL:
  - Run as Administrator (Windows) or with sudo (Linux/Mac)
  - Check network connectivity
  - Install scanning tools (nmap, arp-scan)

PERMISSION DENIED:
  - Windows: Run as Administrator
  - Linux/Mac: Use sudo when starting

================================================================================
PORTS USED
================================================================================

- 5100: Client web interface (can be changed with CLIENT_PORT env var)
- Outbound to server port 5000 (or your configured server port)

================================================================================
UNINSTALLING
================================================================================

RECOMMENDED (Windows installer):
  Settings → Apps → Uninstall **TechHand Remote Support** (Administrator approval
  once). This removes:
    - Program Files\TechHand\Remote Support\
    - TNTRemoteHost Windows service
    - Login startup shortcut (all user profiles on the PC)
    - %APPDATA%\TNTClient (config, logs, keys — all user profiles)
    - %ProgramData%\TNTClient (remote host credentials and service logs)

Manual cleanup (advanced / portable folder install):
  Run as Administrator from the folder containing TNT_Client.exe:
    TNT_Client.exe --uninstall-cleanup
  Or: install_tnt_remote_service.bat uninstall  (delegates to the exe when present)

Dev / source tree (no Inno installer):
  1. Stop the client (close the window or Ctrl+C)
  2. TNT_Client.exe --uninstall-cleanup   (Windows, as Administrator)
  3. Delete the TNT_Client folder if anything remains

NOTE: Uninstall does not remove optional separate components such as the CaddyTNT
service (LLM host). Deactivate the device in TNT admin if it should disappear
from your fleet list.

================================================================================
SUPPORT
================================================================================

- Check README.md in this folder
- Review logs in tnt_client.log
- Contact your system administrator
- Check server at http://your-server:5000/clients-management

================================================================================
SECURITY AND SINGLE-INSTANCE (2026)
================================================================================

- Only one TNT Client should run per machine per port. If the port is busy, set
  CLIENT_PORT in start_client.bat (Windows) or the environment (Linux) before starting.
- dist/ and build/ folders are only needed to rebuild the .exe; you do not need to
  delete them for normal operation.
- The TNT server registers desktop clients only when a valid user JWT is supplied,
  unless the operator explicitly sets TNT_ALLOW_LEGACY_CLIENT_REGISTER=1 on the server
  for isolated lab use (never in production Internet exposure).
- After login, optionally enter an organization API key (tnt_...) and complete owner
  TOTP verification in the Setup page so this PC can run queued org scan jobs.

================================================================================
REMOTE HOST SERVICE (lock-screen / unattended remote support) - WINDOWS
================================================================================

By default, TechHand Remote Support runs inside the logged-in user's session.
That cannot see the Windows lock screen, the sign-in screen, or UAC prompts, and
it only starts after a user logs in. For always-available remote support
(including before/at the lock screen), the SYSTEM "Remote Host" service must be
installed on the machine.

RECOMMENDED INSTALL (Windows):
  Run TechHand-Remote-Support-Setup.exe (build with build_installer.bat). The
  installer asks for Administrator approval once, installs the client to
  Program Files, registers the TNTRemoteHost service (auto-start), and optionally
  adds a login startup shortcut. The tray app itself runs as a normal user — no
  daily UAC prompts.

ARCHITECTURE:
  - TNTRemoteHost service (LocalSystem, auto-start at boot) holds the connection
    to the TNT server and, when a session is requested, launches a capture agent
    INTO the active session as SYSTEM. The agent follows the input desktop, so it
    can show/control the lock, sign-in, and UAC (secure) desktops.
  - The per-user TNT Client tray app still provides the local UI and scanning
    after login. The two coexist; sessions are never double-hosted.

AFTER INSTALL:
  1. Complete Setup in the browser (http://127.0.0.1:5100/setup) so the server
     URL + device key are written to the machine-wide store:
     C:\ProgramData\TNTClient\remote.json
     (the device key is DPAPI-encrypted; the file is locked to SYSTEM + Admins).
  2. Confirm:  sc query TNTRemoteHost     (should show STATE: RUNNING)

LEGACY / PORTABLE EXE (no Inno installer):
  - Open Setup and click "Install Remote Host" (one-time UAC), or run
    install_tnt_remote_service.bat as Administrator (advanced / troubleshooting).

VERIFY IT IS WORKING:
  - Client Setup page shows a "Remote Host service" banner:
      running and connected  -> full lock-screen capability is ready
  - Server side: the Clients list exposes "remote_host_online" per device and
    GET /api/organizations/<org_id>/remote-devices/<device_id>/readiness returns
    {"readiness": "full"} when the service is connected.
  - Logs: C:\ProgramData\TNTClient\remote_service.log
          C:\ProgramData\TNTClient\remote_agent.log
          C:\ProgramData\TNTClient\remote_status.json  (heartbeat)

UNINSTALL:
  - Use Windows Settings → Apps → Uninstall TechHand Remote Support (full cleanup), or
  - TNT_Client.exe --uninstall-cleanup  (Run as Administrator), or
  - install_tnt_remote_service.bat uninstall  (when TNT_Client.exe is in the same folder)

NOTES:
  - Lock-screen / sign-in capture has no user to grant consent, so it requires
    the organization's unattended opt-in + device binding (enforced server-side).
    Attended consent prompts still appear when a user is logged in.
  - Multiple monitors: a display picker appears in the viewer toolbar when the
    remote machine has more than one screen ("All displays" streams them all).
  - Picture quality: the viewer defaults to "Native" for a sharp, 1:1 image; drop
    to 1080p/720p (or B&W) on slow links.

BUILD (Windows developer machine):
  - Client EXE only:  build_client_exe.bat
  - Publishable setup: build_installer.bat  (requires Inno Setup 6.x or 7.x; 7 recommended)
  - Verification:     installer\VERIFY_WINDOWS.md

================================================================================
VERSION INFORMATION
================================================================================

TNT Client Version: 1.0.7
Compatible with TNT Server: 1.0.0+
Last Updated: September 2026

LINUX / SOURCE UPDATES
  Staff Clients → Update pushes the shared TNT_Client.zip (same file as
  Download Client Files). The Linux client verifies SHA-256, overlays the
  tree (keeps venv + client_config.ini), and restarts. Windows EXE installs
  still use /downloads/tnt-client.exe. There is no separate Linux product.

LINUX AUTOSTART
  Setup → Start at login writes a systemd user unit (tnt-client.service)
  or an XDG autostart desktop entry. Same toggle Windows uses.

================================================================================

