AI SERVER CONTROL - WINDOWS CLIENT
==================================

This is the Windows client installer for AI Server Control.

CURRENT CLIENT FEATURES
-----------------------
New local coding clients download the publisher's latest OpenCode, Pi and
DeepSeek packages. The Node bootstrap uses the current release. Existing Pi
installations and saved connection/session settings are preserved.

This client ships remote coding/shared memory, the Windows Model Library, configurable offline
power control, and access to the optional authenticated remote Blender MCP endpoint together.
The server-hosted dashboard now also exposes SGLang, Qwen3.8 Flash Next Indexer Budget and expert
runtime/model-override parameters. Ordinary parameter/UI changes do not require reinstalling this Windows client. You can use each feature independently. The model hard drive stays a permanent
archive; removing the client does not delete the archive or its models.

SSH Terminal and Pi buttons can open Windows PowerShell through the current-user
aiserver-ssh link handler included in client 1.3.7 or later. Client 1.3.8 also
supports the generic setup pack on a PC that already trusts the server. This is a client
integration, not permission for a website to run arbitrary local commands.

Offline power is configurable per Windows user. Choose Auto, Wake-on-LAN, Gigabyte BMC Redfish,
AI Power Bridge, or Disabled. BMC credentials and Power Bridge tokens are stored with Windows DPAPI
for the current Windows user and are not placed in the server's public client profile.
Blender itself stays on the AI server; remote MCP-capable tools use https://<server>:9445/ plus a normal
AI Server API key when Settings -> Blender -> Remote MCP is enabled. The remote OpenCode launcher adds this MCP server automatically for that session. Blender projects and renders can also be opened through \\ai-server\Blender.


It is the SAME installer for:
- Administrator accounts
- Normal User accounts

The AI Server Control account used to sign in determines what the user can see
and do. There is no separate admin executable.

INSTALL
-------
1. Make sure the Ubuntu AI server has already been installed and is running.
2. Copy/extract this folder onto the Windows PC.
3. Double-click:
     AI-Server-Control-Client-Setup.bat
4. The installer automatically looks for:
     192.168.50.95
     ai-server.local
     ai-server
     the ai-server Tailscale peer, when Tailscale is installed
5. For a server-specific download, it validates and trusts the bundled CA,
   then verifies the AI Server appliance API over HTTPS. If using the generic
   setup pack without a bundled CA, it verifies the server using existing
   Windows HTTPS trust and leaves all certificates unchanged. If Windows does
   not yet trust the server, first run INSTALL-AI-SERVER-CERTIFICATE.bat from
   the main setup pack, or obtain the server-specific client package.
6. It installs shortcuts for:
     AI Server Control
     OpenCode - AI Server
     Pi - AI Server
     DeepSeek Harness - AI Server
     AI Remote Coding Setup
     AI Coding - Server Harness
     AI Model Library Setup
     Configure AI Server Offline Power
     Power On AI Server
   into the Start Menu and Desktop.
7. It registers AI Server Control in Windows Installed Apps / Add or Remove
   Programs with an uninstaller.
8. It registers the aiserver-ssh browser terminal handler for this Windows user.
9. The client launches automatically.

There is no default web login. The first administrator is created only during
the original appliance setup, using the one-time token displayed by
RUN-WINDOWS-SETUP.bat. Additional Windows clients sign in with an account that
an AI Server administrator created for them.

WHAT GETS INSTALLED ON THE WINDOWS PC
--------------------------------------
The base client installs a tiny launcher, icon and remote-coding manager scripts.
Local coding harnesses are OPTIONAL and are installed only if the user chooses them later in
AI Remote Coding Setup.

The base client does NOT install:
- AI models
- CUDA
- NVIDIA drivers
- Python
- Docker
- llama.cpp
- vLLM
- Ollama
- ComfyUI

Those all remain on the Ubuntu AI server.

OPEN SSH TERMINAL OR PI FROM A BROWSER
-------------------------------------
1. Install or rerun this current Windows client setup once on each Windows PC
   and for each Windows account that will use browser terminal buttons.
2. In the dashboard sidebar, choose SSH Terminal to connect immediately. The
   username defaults to mike; the dialog lets you change it and reconnect.
   Pi now opens its real interactive terminal inside the separate browser Coding
   Workspace without SSH. Use the Windows terminal launcher only when you
   deliberately run `ai-pi` yourself.
3. Allow that external-app launch when you recognise the dashboard and intended
   server. A visible PowerShell window opens a normal SSH login.
4. Verify a new server's SSH fingerprint at the Ubuntu console before accepting.
   Enter the Ubuntu account password if asked; typing is hidden. The helper does
   not save passwords or suppress host-key verification.

Windows OpenSSH Client must already be installed (Windows Settings > Optional
features). On a remote network, connect Tailscale/VPN before opening a terminal.
The window stays open after the SSH session exits or reports an error so you can read it.
The dashboard login and your Ubuntu SSH account can have different usernames.

Protocol example (connection details only):
  aiserver-ssh://connect?host=192.168.50.95&user=mike&app=shell
  aiserver-ssh://connect?host=100.113.192.1&user=mike&app=pi

Only an interactive SSH login and the fixed Pi command are supported. The launcher rejects arbitrary commands,
scripts, passwords, SSH options, ports, IPv6 addresses, malformed IP addresses,
duplicate fields and unexpected URL fields. Plain IPv4 or DNS hostnames work.
No URL handler is required to open ordinary browser apps or DeepSeek file output.
A website alone cannot start PowerShell: if the handler is missing or blocked,
use the displayed SSH command manually or install the current client. Other
operating systems can use that normal SSH command in their own terminal.
Uninstalling AI Server Control removes its handler only if this installation
still owns it; it does not change another application's protocol registration.

The dashboard never reads this Windows computer's CPU, memory, disks, GPUs,
models or installed applications as AI Server telemetry. Every status shown in
the normal client comes from the verified Ubuntu appliance. Optional local
coding harness mode is clearly separate: only its coding tools and selected
project run on Windows; model inference remains on Ubuntu.

HOW IT WORKS
------------
The installed launcher finds the AI server and opens:

  https://<AI-SERVER>/

in a clean Microsoft Edge app-style window.

The dashboard itself is loaded live from the server. This means:
- the Windows client stays very small
- dashboard updates are made once on the server
- staff PCs immediately receive the updated UI
- no client reinstall is needed for ordinary UI changes



OFFLINE POWER CONTROL
---------------------
Run:
  Configure AI Server Offline Power

to choose how this Windows account starts the server while Ubuntu is powered off:
- Auto: AI Power Bridge -> BMC Redfish -> Wake-on-LAN
- Wake-on-LAN: same local LAN/broadcast domain
- BMC Redfish: direct connection to the motherboard management controller
- AI Power Bridge: a tiny always-on Linux/Raspberry Pi device reachable over LAN/Tailscale
- Disabled: this Windows account will never try to wake the server

You can also configure the boot wait time and whether opening AI Server Control asks before waking the
server or sends the configured power-on request automatically. "Power On AI Server" is a dedicated
shortcut that sends the request immediately.

For BMC mode, the setup stores the credential using Windows DPAPI for the current Windows user. For
Power Bridge mode, the bridge token is stored the same way. The server dashboard stores only non-secret
connection defaults such as BMC host/username, bridge URL and WOL MAC. Never port-forward the BMC or
Power Bridge directly to the public internet; use a trusted VPN/Tailscale path.

WINDOWS MODEL LIBRARY
---------------------
Run:
  AI Model Library Setup

on the Windows computer that owns the hard drive where you want to keep the permanent model archive.
The setup:
- lets you choose any available Windows drive/folder (for example D:\AI-Models)
- creates GGUF, HuggingFace, Drafts, ComfyUI and Downloads subfolders
- creates a dedicated restricted local Windows account only for the SMB model share
- creates the AIModels SMB share and enables per-share SMB encryption where supported
- limits the Windows Firewall SMB rule to the detected AI server address
- registers the share with AI Server Control through an Administrator API key
- does not save that Administrator API key after setup

The Ubuntu server mounts the share at:
  /mnt/ai-model-library

The permanent files stay on the Windows hard drive. AI Server Control can download Hugging Face,
ModelScope and direct-URL models straight into that mounted archive. Ollama retains its own server-side
blob store.

The default load policy is Automatic. When a Windows-library model is selected, the server stages it to
/srv/ai/storage/models/cache when there is enough local space while keeping at least 15% of the server
disk free. Cached copies are least-recently-used and may be evicted automatically. The permanent Windows
copy is never deleted by cache eviction. If the model cannot fit in cache, Automatic mode can load it
directly over SMB instead. Storage -> Windows Model Library can force Always Cache or Direct mode and
change the free-space reserve.

Uninstalling the Windows client never deletes the AI-Models folder, its models, or the Windows SMB share.
The share can be disconnected from the AI server separately from Storage -> Windows Model Library.

REMOTE CODING - USE THE SERVER MODEL FROM THIS PC
--------------------------------------------------
Run:
  AI Remote Coding Setup

This adds an optional second workflow in addition to the server-hosted shortcuts. You can install
OpenCode, Pi Coding Agent and/or DeepSeek Harness locally while keeping all model inference on the
Ubuntu AI server.

Local harness mode:
- the selected harness runs on this Windows PC
- project files, Git, terminal commands, builds and tests run on this Windows PC
- model inference goes to https://<AI-SERVER>/v1
- the stable model name is `active`, so switching the model on the server updates the client
  without editing the local provider configuration

Server harness mode:
- model inference and coding tools/files both run on Ubuntu
- OpenCode and DeepSeek can open their authenticated server browser endpoints
- Pi/default terminal mode uses Windows OpenSSH and the Ubuntu username saved by Remote Coding Setup

The local harness packages are installed under:
  %LOCALAPPDATA%\Programs\AI Server Control\remote-harness\harnesses

They are not installed as system-wide/global npm packages. Removing one local harness leaves the
connection profile and other harnesses intact. Uninstalling AI Server Control removes the whole
per-user remote-harness directory.

REMOTE API KEY SECURITY
-----------------------
Create a per-user key in:
  AI Server Control -> Coding Harnesses -> My API Keys

or use the dedicated Create Remote Harness API Key button.

The full key is shown once by the server. Remote Coding Setup validates it and stores only a
Windows DPAPI-encrypted copy for the current Windows account. At launch it is decrypted into the
harness process environment. Generated OpenCode/Pi/DeepSeek provider files reference environment
variables and do not contain the plaintext key.

The dashboard can also Export Connection Profile. The JSON profile contains server/LAN/Tailscale
addresses, active-model metadata and harness availability but deliberately does NOT contain an API
key. Remote Coding Setup can use that profile or auto-discover the server.

LOCAL HARNESS SHORTCUTS
-----------------------
After a harness is installed locally, shortcuts are created for:
  OpenCode - Remote AI Server
  Pi - Remote AI Server
  DeepSeek - Remote AI Server

Each shortcut asks for a local project folder before giving the harness access to files/tools.
OpenCode runs natively on Windows here; WSL remains a good option for projects that depend heavily
on Linux-specific local tooling.

LOCAL NETWORK
-------------
Normally it connects to:
  https://<server-lan-ip>/

REMOTE / TAILSCALE
------------------
If the local LAN address cannot be reached and Tailscale is installed, the
launcher and Remote Coding tools also look for the ai-server Tailscale peer and connect through it.
Do not port-forward raw model or harness ports to the public internet; use Tailscale/WireGuard/VPN.

USER PERMISSIONS
----------------
Normal users retain all normal AI functions:
- models
- GGUF
- MTP / DSpark / DFlash / EAGLE3 / n-gram
- llama.cpp
- vLLM
- Ollama
- GPU allocation
- model controls
- ComfyUI
- ComfyUI Manager / plugins
- SageAttention / FlashAttention / Nunchaku
- Open WebUI
- AI storage
- server hardware/status
- health check
- account/password settings

Administrator-only:
- service start/stop/restart
- full server logs
- Ubuntu / AI-stack updates
- reboot/shutdown
- Tailscale/network administration
- user management
- security settings
- Cockpit / SSH quick access

The Ubuntu server enforces these permissions. The Windows client cannot bypass
them.

UNINSTALL
---------
Open Windows Settings:
  Apps -> Installed apps -> AI Server Control -> Uninstall

The uninstaller removes:
- the Windows client
- Start Menu/Desktop shortcuts, including OpenCode, Pi and DeepSeek Harness
- its Current User HTTPS trust certificate
- the Installed Apps entry

No server data or AI models are removed.


CERTIFICATE SECURITY
--------------------
If this client ZIP was downloaded from:
  Administrator -> Users -> Download Windows Client

the Ubuntu server inserts its real local CA certificate into the ZIP before
you download it. The installer validates that bundled CA, imports it for the
current Windows user, and then requires the target to answer with the expected
AI Server appliance API contract over trusted HTTPS.

If the client came from the original master setup package before the server was
installed, there is no server-specific certificate yet. That generic package
intentionally refuses to install. Finish the appliance setup, then download a
fresh server-specific Windows client ZIP from AI Server Control. A trust anchor
is never fetched from an unverified web address.


OPENCODE
--------
The Windows client also installs:

  OpenCode - AI Server

on the Desktop and Start Menu.

That shortcut uses the same server discovery as the main AI Server Control
client and opens the server-hosted OpenCode web application on HTTPS port 4443.

That shortcut uses server-hosted OpenCode on Ubuntu. If the user instead chooses OpenCode in
AI Remote Coding Setup, an isolated local OpenCode client can run on the Windows PC while using
the same AI Server unified model API for inference.

This means:
- local GGUF models can be used for coding through llama.cpp
- native Hugging Face models can be used through vLLM
- switching the active model in AI Server Control changes the model OpenCode
  uses through the `ai-server/active` provider
- no cloud API is required for normal local use
- OpenCode skills, agents and MCP configuration live on the AI server


PI CODING AGENT
---------------
The Windows client installs:

  Pi - AI Server

Pi is a terminal application, so this shortcut starts the server-side Pi
launcher through Windows OpenSSH rather than opening a fake browser page. Run
AI Remote Coding Setup once and save the Ubuntu SSH username if the shortcut
asks for it. Pi is also shown in AI Server Control under Launch connected apps
and Coding Harnesses; those buttons copy the verified server SSH command.


DEEPSEEK HARNESS
----------------
The Windows client also installs:

  DeepSeek Harness - AI Server

That shortcut uses the same LAN/Tailscale discovery and trusted server CA as
AI Server Control and opens /api/harnesses/deepseek/open on the dashboard.
Sign in if asked; the server then opens the authenticated shared DeepSeek HTTPS
origin on port 4444. No launch token or account identifier is stored in the shortcut.
For existing Windows shortcuts, rerun AI-Server-Control-Client-Setup.bat from
this updated client package after applying the server update.

That shortcut uses the server-hosted `dsh` package on Ubuntu with one shared
unprivileged service identity, Harness profile/history and `/srv/ai/projects`
tree for authenticated AI Server accounts. AI Remote Coding Setup can alternatively install an isolated local DeepSeek
Harness client on Windows while continuing to use the server's active model. DeepSeek Harness
remains an upstream developer preview, so both server and local installation are optional.

The server keeps DSH on `127.0.0.1:3080`. Remote/LAN access is provided only
through the authenticated TLS reverse proxy on port 4444. Headless
coding tasks can also be launched on the server with `ai-deepseek "task"`.


V8 OPENCODE CODING ENVIRONMENT
------------------------------
The Windows client still remains tiny. The additional coding toolchains in v9
are installed on the Ubuntu AI server, not on every Windows PC.

The "OpenCode - AI Server" shortcut gives users access to the server-side
coding environment, which now includes Node/pnpm, Python/uv, Rust, Go, Java,
.NET, PHP, C/C++, language servers, formatters/linters, GitHub CLI and
Playwright browser testing.

There is no client reinstall requirement when these server-side coding tools or
OpenCode project rules are updated.


SERVER-SIDE OPTIONAL ADD-ON UNINSTALLS
-------------------------------------
The v10 AI Server Control dashboard can uninstall optional OpenCode and curated
ComfyUI add-ons from the server. No Windows client reinstall is needed when those
server-side features are added or removed.

The Windows client itself continues to uninstall normally from:
  Windows Settings -> Apps -> Installed apps -> AI Server Control -> Uninstall


V11 LIVE PERFORMANCE INFORMATION
--------------------------------
The Windows client still loads the dashboard live from the Ubuntu server, so no
client reinstall is required just to receive the v11 performance-information UI.

AI Server Control now shows real server measurements for optional installed
coding/ComfyUI components including current RAM, CPU, process count, disk
footprint, GPU/VRAM relevance, and observed before/after install/toggle/uninstall
deltas.

Because this UI is server-hosted, the information appears automatically on
existing Windows clients after the server is upgraded.


REMOTE SHARED MEMORY (v13.4)
- Local remote harness mode now refreshes shared coding memory from the AI server before launch.
- The launcher keeps retrieved context under the client's managed application-data folder, outside the selected repository. It does not rewrite the project's AGENTS.md.
- On exit, the launcher posts a Git-aware checkpoint back to the AI server so another harness/computer can continue.
- Automatic folder-name mapping still works when no explicit mapping exists.
- New: explicit project mapping lets different local paths/folder names on different computers share one AI Server memory project.
- Mappings are editable in AI Server Control -> Coding Harnesses -> Remote Project Memory Mapping.
- Windows Remote Coding Setup also has option 8 to map a local project folder directly.
- Mapping changes apply to OpenCode, Pi and DeepSeek and are re-resolved when a harness exits.
- A lightweight server-side memory workspace is created automatically for client-only projects; source code does not need to be copied to the AI server.
DEEPSEEK COMPUTER CONTROL
Run AI-Computer-Control.bat to set up, start or stop browser and Windows desktop
control for your server's DeepSeek Harness. Your Qwen model stays on Ubuntu.
Pause Harness tasks before setup. The normal Windows client installer adds a
Computer Control Setup shortcut but does not enable desktop control by itself.
After starting the Windows helper, use Computer control below the DeepSeek
message box to turn access on or off for all sessions. Each helper start leaves
access OFF. Update through Set up or update, then refresh DeepSeek with Ctrl+F5.
