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:

    1. [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:

    1. 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:

    1. 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:

    1. Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Undefined

    2.3 Install the Node.js Runtime

    Check whether Node.js and npm are already installed:

    1. node -v
    2. npm -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:

    1. 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:

    1. 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:

    1. Install-Module Microsoft.PowerShell.SecretManagement -Scope CurrentUser
    2. Install-Module Microsoft.PowerShell.SecretStore -Scope CurrentUser
    3. Set-Secret -Name ModelApiKey -Secret (Read-Host -Prompt "Enter API key" -AsSecureString)

    Before starting the daemon, inject the key into the current process environment:

    1. $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:

    1. {
    2. "listen": "127.0.0.1:<port>",
    3. "dataDir": "D:\\assistant\\data",
    4. "logLevel": "info",
    5. "providers": [
    6. {
    7. "name": "default",
    8. "baseUrl": "https://<service-domain>/v1",
    9. "apiKey": "${env:MODEL_API_KEY}",
    10. "model": "<model-name>",
    11. "timeoutMs": 60000,
    12. "maxRetries": 2
    13. }
    14. ]
    15. }

    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.