Self-Hosted AI Assistant on Windows: A Reproducible Deployment Guide
Prepare a Windows environment for a self-hosted AI assistant with clear data boundaries, local-only access, a Node.js runtime, and secure model API credentials. This guide covers prerequisites, configuration, and the initial download step, with project-specific settings left to the official documentation.
1. Architecture and Boundaries
A self-hosted assistant consists of three components:
- Local daemon: Manages session state, registers skills, and validates permissions.
- Model adapter layer: Converts standardized chat requests into a compatible REST API format. It connects to the remote model service over HTTPS only during inference.
- Interaction interfaces: A browser console, command-line interface, and messaging gateway.
Data Boundaries
Conversation history, uploaded attachments, configuration files, and audit logs remain in the local data directory. The remote service receives only the prompts and context required for inference—not the entire contents of that directory.
Network and Port Requirements
| Purpose | Access scope | External exposure |
|---|---|---|
| Console and local API | A port on 127.0.0.1, as specified by the listen configuration field |
No |
| Outbound model service requests | HTTPS on port 443 | Approved domains only |
| Messaging webhooks | Through an official gateway or an enterprise reverse proxy | Subject to enterprise policy |
For light, single-user workloads, at least 8 GB of RAM is recommended, with approximately 2 GB of disk space reserved for the runtime and logs. For shared use, deploy the daemon on a dedicated host on the internal network and use the local machine only as a client.
This guide uses Node.js as the JavaScript runtime example. Refer to the assistant project’s official documentation for its name, version, and supported parameters.
2. Prepare the Environment and Dependencies
2.1 Check the System Architecture
Run the following command in PowerShell. A result of True indicates a 64-bit operating system:
[Environment]::Is64BitOperatingSystem
2.2 Check the PowerShell Execution Policy
PowerShell execution policies restrict script execution; they are not a security boundary. Organization-managed policies take precedence over local settings.
First, inspect the policy for each scope:
Get-ExecutionPolicy -List
If the current user scope is set to Restricted, you can change it to RemoteSigned. This permits locally created scripts to run, while scripts downloaded from the internet require a trusted digital signature. Changing the current user scope does not require administrator privileges:
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
If execution policy is centrally managed through Group Policy (GPO), local changes may be overridden. Contact your IT department rather than attempting to bypass the policy.
To remove the current-user override, run:
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Undefined
2.3 Install the Node.js Runtime
Check whether Node.js and npm are already installed:
node -vnpm -v
Choose a currently maintained LTS major release, using the version information published by Node.js. Install it using the official MSI installer or winget, for example:
winget install OpenJS.NodeJS.LTS
During installation, make sure the option to add Node.js to PATH is enabled. After installation, reopen the terminal and run node -v again to confirm the version.
2.4 Plan the Data Directory
Use a data directory path without spaces, non-ASCII characters, or special characters, such as:
D:\assistant\data
Special characters in a path may cause the daemon to fail when parsing its configuration.
2.5 Configure Firewall Access
The assistant requires only local loopback access. There is no need to open an inbound public port. Bind the console to 127.0.0.1.
3. Obtain Credentials and Configure Secrets
3.1 Create a Model Service API Key
Create an API key in the model service platform’s key management page. Set a usage limit and restrict which models the key can access.
3.2 Record the Required Connection Settings
Record these three values:
- API base URL: Commonly formatted as
https://<service-domain>/v1. - Default model name: Represented here by
<model-name>. - Maximum context length: Used to limit the length of individual requests in the configuration.
For model services compatible with the OpenAI API protocol, the orchestration layer does not require code changes when the base URL and API key are configured correctly.
3.3 Store the API Key Securely
Do not put the key in configuration files, commit it to a code repository, or write it to logs. The recommended approach is to store it using the SecretManagement and SecretStore modules:
Install-Module Microsoft.PowerShell.SecretManagement -Scope CurrentUserInstall-Module Microsoft.PowerShell.SecretStore -Scope CurrentUserSet-Secret -Name ModelApiKey -Secret (Read-Host -Prompt "Enter API key" -AsSecureString)
Before starting the daemon, inject the key into the current process environment:
$env:MODEL_API_KEY = Get-Secret -Name ModelApiKey -AsPlainText
This sets a process-scoped environment variable for the current session rather than a persistent system-wide variable.
3.4 Create the Configuration File
On first launch, the application generates a configuration file in the user directory. The following field names are generic examples; consult the project’s configuration documentation for the actual schema:
{"listen": "127.0.0.1:<port>","dataDir": "D:\\assistant\\data","logLevel": "info","providers": [{"name": "default","baseUrl": "https://<service-domain>/v1","apiKey": "${env:MODEL_API_KEY}","model": "<model-name>","timeoutMs": 60000,"maxRetries": 2}]}
The apiKey field references an environment variable rather than containing a plaintext key. Adjust the timeout and retry count to suit your network conditions.
4. Download, Verification, and Installation
4.1 Obtain the Installation Files
Download the installation script from the project’s official releases page.
