Windows Isolated Dev Environment

Hermes on Windows — Isolated Dev Environment

Set up Hermes on a Windows PC under a dedicated non-admin standard user account. Use case: GPU-accelerated creative/dev work (Three.js, Blender, UE5, web game dev) while keeping personal data on the main account completely isolated.

When To Use

• User wants Hermes on a Windows machine but doesn't trust it with personal files
• Dedicated dev box with a GPU (your GPU, e.g. 12-24GB VRAM, etc.) for rendering-heavy work
• Cross-machine setup: Mac for daily/personal, Windows for GPU dev
• Security-conscious: limit blast radius if Hermes is compromised

Architecture

MAIN ACCOUNT (<user>):
  - Install UE5, Steam, etc. via admin (one-time)
  - Personal files stay here — Hermes cannot access them

HERMES-DEV ACCOUNT (standard user, NOT admin):
  - Python, Node, Git (user-space installs)
  - Hermes (git clone + venv)
  - Blender (portable zip)
  - VS Code (portable)
  - Runs system-wide installed programs (UE5, browsers)
  - All Hermes data in C:\Users\hermes-dev\

Step-by-Step Setup

1. Create the account

Windows Settings → Accounts → Other users → Add account. Name: hermes-dev (or whatever). Type: Standard user (NOT admin).

This account:

• Cannot install system-wide software
• Cannot access C:\Users\<main-user>\
• Cannot modify system settings or registry
• CAN run programs, browse web, use GPU

2. Install per-user tools (as hermes-dev)

All support per-user installs (no admin needed):

Python 3.11+: Download "Windows installer (64-bit)" → "Install for current user" (not system-wide). Adds to PATH automatically for that user.

Node.js: Download .zip (NOT .msi) → extract to C:\Users\hermes-dev\nodejs\. Add to PATH in user environment variables.

Git: Download portable Git → extract to C:\Users\hermes-dev\git\. Or if Git is already installed system-wide, non-admin users can read it.

VS Code (portable mode): Download .zip → extract to C:\Users\hermes-dev\vscode\. Launch with --user-data-dir to keep settings isolated.

3. Install Hermes

Open PowerShell as hermes-dev:

cd ~
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
python -m venv venv
.\venv\Scripts\activate
pip install -e .
python run_agent.py

4. Blender (portable zip)

Download .zip from blender.org → extract to C:\Users\hermes-dev\blender\. Hermes can drive it via the blender-automation MCP skill. Models land in workspace\blender-models\.

5. UE5 (system-wide, main account installs)

UE5 requires admin to install via Epic Games Launcher. Install from main account. The hermes-dev standard user can run UE5 (read+execute), just can't install/uninstall.

If UE5 is in C:\Program Files\Epic Games\UE_5.x, standard users can execute it by default. If not, grant access:

icacls "C:\Program Files\Epic Games\UE_5.x" /grant hermes-dev:(OI)(CI)RX

Workspace Structure

C:\Users\hermes-dev\
├── hermes-agent\          # Hermes source + venv
├── .hermes\               # Hermes config, profiles, memories
│   └── profiles\
│       └── designer\      # Profile for Three.js/Blender/UE5 work
│           ├── config.yaml
│           ├── skills\    # threejs-*, blender-automation, ue-* skills
│           └── scripts\
├── workspace\             # All dev projects go here
│   ├── threejs-scenes\
│   ├── blender-models\
│   └── ue5-projects\
└── vscode\                # Portable VS Code

Security Boundaries

HERMES CAN ACCESS:

• C:\Users\hermes-dev\ (its own files)
• GPU (your GPU, etc.) — browser rendering, Blender, UE5
• Network — API calls, subscriptions
• Chrome/Edge — Three.js preview

HERMES CANNOT ACCESS:

• C:\Users\<main-user>\ — Windows ACL blocks this by default
• System-wide installs (read-only for standard users)
• Registry (read-only)
• Other user profiles
• Windows credentials

WEAK POINT: Network access is still open. For extra security, add a Windows Firewall rule for the hermes-dev user that blocks outbound except API endpoints (OpenRouter, Anthropic, etc.)

Designer Profile Config

The profile on the Windows box should have:

• Skills: threejs-*, blender-automation, ue-*, game-dev-with-hermes
• Disabled toolsets: discord, email, social-media, financial-markets
• Enabled toolsets: browser, terminal, file, web, image_gen
• No access to Mac-only skills (imessage, apple-notes, findmy, etc.)

Cross-Machine Skill Sync

Two skill tiers in the windowshermes repo:

1. Shared skills (repo root skills/) — installed to ALL profiles by install.sh. For skills every profile needs (memory system, debugging, etc.).
2. Profile-specific skills (each profile's skills/) — for domain-specific skills only that profile needs.

Critical gap to watch for: New profiles often ship with SOUL.md + AGENTS.md + config.yaml but NO skills directory. Always verify each profile has its required skills after initial setup. See references/windowshermes-skill-inventory.md for the full per-profile skill list and sync commands. See references/magnus-skills-for-windows.md for which Magnus Agent-Skills are recommended for Windows game dev profiles.

Skills the ue5-coder profile needs (not exhaustive, check current senna profile):

• karpathy-coding-discipline — surgical coding, no drive-by refactors
• test-driven-development — RED-GREEN-REFACTOR cycle
• systematic-debugging — 4-phase root cause debugging
• ue-* skills — Unreal Engine specific patterns (cpp-foundations, actor-component, gameplay-abilities, etc.)
• game-dev-memory-system — memory architecture (can be shared)

Sync workflow:

Mac (source of truth) → git push → Windows (pull + install.sh)

• Mac senna profile is the canonical source for skills
• Push to windowshermes repo → pull on Windows → run install.sh
• install.sh copies shared skills to all profiles; profile-specific skills live in profiles/<name>/skills/
• After pulling, verify: ls ~/.hermes/profiles/ue5-coder/skills/ should NOT be empty

Cross-Machine Config Transfer

When moving Hermes config from Mac to Windows:

What to copy:

• ~/.hermes/config.yaml (settings)
• ~/.hermes/auth.json (provider auth)
• ~/.hermes/.env (API keys)
• ~/.hermes/profiles/<name>/ (config, skills, plugins, scripts)
• Mnemosyne memory export (via mnemosyne_export)

What NOT to copy:

• ~/.hermes/hermes-agent/ (reclone fresh — different OS, different venv)
• node_modules/ (reinstall fresh)
• Platform-specific configs (launchd, macOS paths)
• Mac-only plugin state

What to recreate:

• Cron jobs (list with hermes cron list --all on Mac, recreate on Windows)
• Platform connections (Discord bot token works on both, but gateway runs one at a time)
• Any symlinks (Windows uses junctions or copies instead)

Private Profiles Repo Pattern

Store domain-specific Hermes profiles in a private GitHub repo. Both Mac and Windows pull from it.

repo/
├── README.md
├── install.sh              # one-command setup (supports --setup-ollama, --setup-llamacpp)
├── .env.example            # template with placeholder API keys
├── .gitignore              # blocks .env, .DS_Store, node_modules
├── profiles/
│   ├── ue5-coder/
│   │   ├── SOUL.md         # compressed DSL persona
│   │   ├── AGENTS.md       # domain conventions
│   │   └── config.yaml     # backend toggle (ollama/llamacpp), model, inference settings
│   ├── threejs-coder/
│   ├── blender-coder/
│   └── designer/
├── knowledge/              # wiki snapshots for offline reference
│   ├── ue5/
│   ├── threejs/
│   ├── blender/
│   └── design/
└── scripts/
    ├── download-model.sh   # Pull GGUF models from HuggingFace (--list for options)
    ├── build-llamacpp.sh   # Build llama.cpp from source with CUDA
    ├── start-llamacpp.sh   # Launch server with auto-tuned GPU settings
    └── create-modelfile.sh # Convert GGUF → Ollama Modelfile

Config with dual backend support — each profile's config.yaml has a backend toggle:

backend: llamacpp    # or 'ollama'

ollama:
  base_url: http://127.0.0.1:11434/v1
  model: hf.co/unsloth/Qwen3.6-35B-A3B-GGUF:UD-IQ2_XXS

llamacpp:
  base_url: http://127.0.0.1:8080/v1
  model_dir: ~/models/gguf
  model_file: Qwen3.6-35B-A3B-UD-IQ2_XXS.gguf
  server_binary: ~/llama.cpp/build/bin/llama-server
  num_gpu_layers: 999
  context_size: 16384
  flash_attention: true
  cache_type_k: bf16
  cache_type_v: bf16
  port: 8080

Knowledge snapshots — copy LLM-Wiki pages into the repo so the Windows machine has offline reference material. The agent loads skills at runtime; knowledge/ is for human reference or agent RAG.

Sync workflow:

• Mac is source of truth for knowledge updates
• git push from Mac, git pull on Windows, re-run install.sh
• Each machine has its own .env (never committed)

Quick Setup Flow (8 Steps)

After creating the Windows account, run these in order:

# 1. Python (download .exe → "Install for current user", check "Add to PATH")
# 2. Git (download portable .zip → extract to C:\Users\<account>\git\)

# 3. Clone your profiles repo
gh repo clone <owner>/<repo-name>
cd <repo-name>
copy .env.example .env
notepad .env  # fill in API keys

# 4. Install Hermes
cd ~
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
python -m venv venv
.\venv\Scripts\activate
pip install -e .

# 5. Run the profile installer
cd ~\<repo-name>

# Option A: Ollama (easy)
.\install.sh --setup-ollama

# Option B: llama.cpp (full control)
.\install.sh --setup-llamacpp

# 6. Start
# With Ollama:
ollama serve
# With llama.cpp:
.\scripts\start-llamacpp.sh ~/models/gguf/<model>/<file>.gguf

# 7. Launch Hermes
hermes --profile ue5-coder

Local Inference: llama.cpp vs Ollama

Both wrap the same inference engine (llama.cpp). The difference is control vs convenience.

Use Ollama when: quick setup, don't need fine-tuning control, standard models. Use llama.cpp when: aggressive quantization on constrained VRAM, need exact GPU layer offload, using Unsloth MTP models, debugging gibberish output (fix with bf16 cache).

For your GPU (12GB VRAM) with aggressive quants (UD-IQ2_XXS), llama.cpp's knobs matter — especially --n-gpu-layers for partial CPU offload and --cache-type-k bf16 --cache-type-v bf16 to fix quality issues.

llama.cpp server mode (replaces Ollama):

git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j

./llama.cpp/build/bin/llama-server \
  -m path/to/model.gguf \
  --n-gpu-layers 999 \
  --ctx-size 16384 \
  --flash-attention \
  --cache-type-k bf16 \
  --cache-type-v bf16 \
  --port 8080

Then Hermes config uses base_url: http://127.0.0.1:8080/v1 instead of Ollama's 11434.

Secrets in Private Repos

When storing profiles in a private GitHub repo, use .env.example + .gitignore:

repo/
├── .env.example    ← committed, has placeholder values
├── .gitignore      ← blocks .env from commit
└── .env            ← local only, has real keys

.gitignore must contain: .env, .env.local, .env.*.local

Each machine creates its own .env from the template. Safe to include API keys in a private repo's .env if you create dedicated keys for that machine.

CPU Offloading

When the model doesn't fit fully in VRAM, layers spill to system RAM. This is handled transparently by Ollama/llama.cpp — Hermes doesn't know or care.

With 32GB system RAM, CPU offload is viable. Rule of thumb: each 1GB offloaded costs ~2-3 tok/s.

MCP Server Configuration

Windows profiles need MCP servers configured in each profile's config.yaml (profile isolation — the global config is NOT read). The most common MCP server for Windows is Mnemosyne (memory), but the pattern applies to any MCP server.

Mnemosyne MCP Server

Mnemosyne has a built-in MCP server (mnemosyne mcp, stdio transport). This is the way to use Mnemosyne on Windows where it's not natively integrated like on Mac.

Install on Windows:

pip install "mnemosyne-memory[mcp]"

The [mcp] extra pulls the MCP SDK dependencies. Without it, mnemosyne mcp fails with "MCP not installed".

Add to each profile's config.yaml:

mcp_servers:
  mnemosyne:
    command: mnemosyne
    args: ["mcp"]
    enabled: true
    env:
      MNEMOSYNE_DB_PATH: "C:\\Users\\hermes-dev\\.hermes\\mnemosyne.db"

Key details:

• Uses stdio transport (default) — no port, no network exposure
• Each profile can share one DB or have its own (set different MNEMOSYNE_DB_PATH per profile)
• The command is mnemosyne (the CLI entry point), NOT a full path — it resolves via PATH in the venv
• Tools register as mcp_mnemosyne_* after Hermes restart

Verify:

hermes mcp list                    # should show mnemosyne with ✓
hermes mcp test mnemosyne          # should show tools discovered

Other MCP Servers

Same pattern — add to mcp_servers in profile config. Examples:

mcp_servers:
  codegraph:
    command: codegraph
    args: ["serve", "--mcp"]
    enabled: true

  blender:
    command: uvx
    args: ["blender-mcp"]
    enabled: true

See native-mcp skill for full MCP client configuration reference.

Plugin Configuration

Hermes plugins (pip packages with hermes_agent.plugins entry points) are enabled per-profile via the plugins section in config.yaml. This is separate from MCP servers.

rtk-rewrite Plugin

Rewrites terminal commands through RTK for lower-context tool output. Requires two things:

1. Pip package: pip install rtk-hermes
2. RTK binary in PATH: The rtk CLI must be available. On Windows, check with where rtk.

Add to each profile's config.yaml:

plugins:
  disabled: []
  enabled:
    - rtk-rewrite

Config via env vars (optional):

• RTK_HERMES_MODE: rewrite (default), suggest, or off
• RTK_HERMES_TIMEOUT_MS: per-rewrite timeout (default 2000)
• RTK_HERMES_BACKENDS: local (default), or comma-separated list

Other Plugins

Same pattern. Common plugins for Windows profiles:

plugins:
  disabled: []
  enabled:
    - rtk-rewrite
    - disk-cleanup

Profile Config Completeness Checklist

Windows profiles often ship with SOUL.md + AGENTS.md + config.yaml but are missing critical sections. After cloning/pulling the windowshermes repo, verify each profile's config.yaml has:

• backend — llamacpp or ollama
• llamacpp or ollama section — model, base_url, server settings
• skills — category + paths to shared skills
• inference — temperature, top_p, max_tokens, etc.
• mcp_servers — at minimum Mnemosyne for memory
• plugins — at minimum rtk-rewrite if rtk is installed
• description — one-line profile purpose

Common gap: Profiles in the windowshermes repo (as of 2026-06-09) have NONE of the last two sections. Always add them when setting up a new Windows machine.

Memory System

For game dev, set up a three-layer memory system (Mnemosyne + Fabric + Obsidian). See game-dev-memory-system skill for full setup and conventions.

Quick setup on Windows PC:

# Run the setup script from the skill
.\skills\game-dev\game-dev-memory-system\scripts\setup-game-dev-memory.ps1

Memory layers:

1. Mnemosyne — Hot facts (auto-injected every turn). On Windows, use MCP server mode (see MCP Server Configuration above).
2. Fabric — Decision history (ranked recall)
3. Obsidian — Knowledge wiki (file tools)

Pitfalls

• UE5 admin requirement: Epic Games Launcher needs admin. Install once from main account, run from hermes-dev.
• Node.js .msi vs .zip: The .msi installer requires admin. Always use .zip for per-user installs.
• Python PATH: "Install for current user" option is easy to miss — it's a small checkbox during setup.
• Windows Defender: First run of Hermes may be slow as Defender scans Python/Node. Add exclusion for C:\Users\hermes-dev\ to speed things up.
• Long paths: Windows has a 260-char path limit by default. Enable long paths in registry (requires admin once) or keep project directories short.
• GPU in browser: Three.js WebGL/WebGPU uses whatever GPU the browser has access to. Chrome/Edge on Windows will use the discrete GPU by default. No special config needed.
• Port conflicts: If running Hermes on both Mac and Windows simultaneously, they're different machines so no conflict. But if gateway is exposed, only one should be the public endpoint.
• Empty profile skills dir: Profiles often ship with SOUL.md + AGENTS.md + config.yaml but forget the skills directory. After cloning/pulling the windowshermes repo, always verify ls profiles/ue5-coder/skills/ is non-empty. If empty, copy required skills from senna's profile on the Mac and push.
• Missing mcp_servers/plugins in profiles: The windowshermes repo profiles (as of 2026-06-09) have NO mcp_servers or plugins sections. Every profile needs both. Without mcp_servers, Mnemosyne memory doesn't work. Without plugins, rtk-rewrite and other plugins are silent no-ops. Always add these sections when setting up a new Windows machine or creating new profiles.
• Mnemosyne MCP vs native: On Mac, Mnemosyne is a native Hermes plugin (tools injected directly). On Windows, use the MCP server mode (mnemosyne mcp) instead. The tools register as mcp_mnemosyne_* (prefixed) rather than bare mnemosyne_*. Same functionality, different integration path.
• rtk binary separate from rtk-hermes: pip install rtk-hermes installs the Hermes plugin. The rtk CLI binary is a separate install. If where rtk fails, the plugin silently passes commands through unrewritten (fail-open). Always verify both are installed.
• MCP [mcp] extra: pip install mnemosyne-memory alone does NOT install MCP deps. Use pip install "mnemosyne-memory[mcp]" or mnemosyne mcp will fail with "MCP not installed".
• Ollama auto-start: Ollama installs as a Windows service and starts on boot. Verify with ollama list. If not running: ollama serve.
• CUDA 13.2: Do NOT use CUDA 13.2 with Unsloth GGUFs — produces gibberish output. Use CUDA 12.x.
• Model file naming: Unsloth GGUF filenames include quantization suffix (e.g., UD-IQ2_XXS). When pulling via Ollama, use the full hf.co/unsloth/<model>-GGUF:<tag> format.