Skip to content

windows_install.md

Latest commit

 

History

History
210 lines (136 loc) · 7.03 KB

windows_install.md

File metadata and controls

210 lines (136 loc) · 7.03 KB

Installation on Windows (PowerShell)

Because the Summoner SDK spans multiple repositories, we do not ship a one-line pip install. On Windows we provide a PowerShell installer that mirrors our POSIX flow and composes the SDK for you.

Use the script in the SDK template repo: build_sdk_on_windows.ps1. It orchestrates cloning the right repos, creating a virtual environment, installing dependencies, and wiring modules listed in your build.txt.

Warning

The Rust/Tokio server is not available on Windows. Any version: "rust" in your config is ignored on Windows and the server runs with the Python backend. If you want to experiment with the Rust server, see WSL2 notes below.

For Linux/macOS users, see the POSIX installer here.

A Template-Based SDK (Windows edition)

The summoner-sdk repository is a GitHub template. You do not modify it in place: click Use this template to generate your own SDK repo that contains only the installer and composition logic.

You decide which features to include by editing build.txt in your new repo. The Windows installer then composes your SDK accordingly — pulling in the SDK core and any modules you list.

Note

The template's default build.txt references:

Required Tools and What the Script Runs

On Windows, the PowerShell script build_sdk_on_windows.ps1 replaces the POSIX script build_sdk.sh and drives the same high-level steps:

  • Clone summoner-core and requested modules
  • Create a Python venv/
  • Install Python dependencies
  • Normalize composed-module imports (rewrites from tooling.X to from summoner.X)
  • Skip building the Rust server (not supported on Windows)

Install these first:

  • PowerShell (Windows Terminal or PowerShell 7+ recommended)

  • Git for Windows – https://git-scm.com/download/win

  • Python 3.9+ available as python or via the launcher py -3

    python --version    # or: py -3 --version

Tip

You can run all steps from VS Code's integrated terminal (PowerShell profile).

Build the SDK with a Custom build.txt

Step 1: Create your SDK repository

  1. Open the summoner-sdk template
  2. Click Use this template → Create a new repository
  3. Name your project and confirm

Clone your new repository:

git clone https://github.com/<your-account>/<your-sdk-repo>.git
cd <your-sdk-repo>

Step 2: Choose features in build.txt (optional)

Edit build.txt to list modules you want pulled into your SDK. Example:

https://github.com/Summoner-Network/extension-agentclass.git:
aurora

Tip

Aurora is optional. You can include it from the start or add it later and re-run setup. For the extension overview, see Agent Extensions. For the Aurora API itself, see aurora and the SummonerAgent reference.

You can modify build.txt any time and re-run the installer.

Step 3: Run the Windows installer

Allow script execution for this session only:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Run setup:

.\build_sdk_on_windows.ps1 setup

This will:

  • Detect Python/Git
  • Create venv/
  • Clone summoner-core and modules from build.txt
  • Install Python dependencies
  • Normalize composed-module imports (rewrites from tooling.X to from summoner.X)
  • Skip Rust server build on Windows

Activate the environment:

.\venv\Scripts\Activate.ps1

Your prompt should show (venv).

🔁 The demo below was run on POSIX; the Windows flow is analogous.

Step 4: Quick server check (Python backend)

Start a minimal local server:

.\build_sdk_on_windows.ps1 test_server

You should see it listening on 127.0.0.1:8888. Open another terminal (activate venv) and connect with your client; messages will broadcast to other connected clients.

Note

On Windows, this always uses the Python server.

Script commands (PowerShell)

.\build_sdk_on_windows.ps1 <action> [variant]
  • setup [build|test_build] — Compose/install the SDK (default: build)
  • deps — Reinstall Python dependencies into the existing venv/
  • test_server — Launch a minimal local server (Python backend)
  • delete — Remove generated artifacts (venv/, temp clones, etc.)
  • reset — Strong clean + re-setup
  • clean — Light cleanup of caches/temp files

Tip

Edit build.txt any time and re-run setup. The installer is idempotent.

Optional: Using WSL2 to try the Rust server

If you require Rust/Tokio parity with Linux/macOS:

  1. Install Ubuntu on WSL2:

    wsl --install -d Ubuntu

  2. In the Ubuntu terminal, follow the Linux/macOS guide exactly (install Python + Rust with rustup, then run build_sdk.sh).

  3. Networking usually forwards localhost between Windows and WSL2. If needed, bind to 0.0.0.0 or find your WSL IP:

    hostname -I

Warning

WSL2 works well for many setups but isn't fully certified across environments yet.

Troubleshooting

If you see "Script is blocked by policy", then run:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

If you see "Python 3 not found", then install Python 3.9+ and ensure python or py is on PATH. Restart the terminal and verify:

python --version    # or: py -3 --version

If you see "Dependency build errors", then upgrade packaging tools and retry:

python -m pip install -U pip wheel

If the error mentions a C/C++ compiler on Windows, install the Microsoft C++ Build Tools and re-run the installer.

If you see "Port already in use", then change the port in your config or stop the conflicting process.

« Previous: Installation (Linux/macOS)    |    Next: Quickstart »