Platform Guide
Windows Setup Guide
A complete walkthrough for installing and configuring SessionForge on Windows 10 and Windows 11.
Overview
SessionForge works on Windows 10 (version 1809+) and Windows 11. Because Windows does not natively support POSIX terminal interfaces (PTYs), the agent uses a tiered approach to create the best possible terminal experience based on what you have installed.
Before installing the agent, you need one of the following environments set up. Follow the relevant section below, then return to install the agent.
WSL2 Setup (Recommended)
WSL2 (Windows Subsystem for Linux 2) provides a full Linux kernel inside Windows. The SessionForge agent uses it to create real PTY sessions, giving you the same terminal experience as native Linux.
Step 1 — Install WSL
Open PowerShell as Administrator and run:
This installs WSL2 and the Ubuntu distribution by default. If you already have WSL installed, this is a no-op.
PowerShell showing wsl --install output
Screenshot placeholder
Step 2 — Restart
A system restart is required after installing WSL2. Save your work and reboot before continuing.
Step 3 — Complete Linux Setup
After restart, the Ubuntu terminal will open automatically and prompt you to create a Linux username and password. This is your WSL user — it does not need to match your Windows username.
Ubuntu first-run setup prompting for username
Screenshot placeholder
Step 4 — Verify WSL is Running
Check the installed distro and WSL version:
You should see your distro listed with VERSION 2. If it shows version 1, upgrade it:
Step 5 — Install Claude Code inside WSL
Open your WSL terminal (Ubuntu) and run:
claude within the WSL shell.Git Bash Alternative
If you cannot use WSL2 (e.g., on restricted corporate machines), Git for Windows provides Git Bash — a POSIX-compatible shell that enables a better terminal tier than the raw pipe fallback.
Download Git for Windows
Visit git-scm.com/download/win and download the latest installer.
git-scm.com download page
Screenshot placeholder
Run the installer
Accept the defaults. On the Adjusting your PATH environment screen, select “Git from the command line and also from 3rd-party software”.
Verify the install
Open a new PowerShell window and run:
You should see a version string like git version 2.44.0.windows.1.
Install the Agent
Once WSL2 or Git Bash is set up, install the SessionForge agent.
Run the installer (PowerShell as Administrator)
Replace YOUR_KEY with an API key from Settings → API Keys.
Verify the agent is running
You should see the machine status, active tier (WSL / Git Bash / ConPTY / Pipes), and any open sessions.
Check the dashboard
Navigate to your SessionForge dashboard. Your machine should appear online within 30 seconds.
Dashboard showing machine online
Screenshot placeholder
PTY Tier Explained
The agent automatically selects the best available terminal backend when starting a session. Tiers are evaluated in order — the highest available tier is used.
Full POSIX PTY inside a Linux kernel. All terminal features work: ANSI color, cursor movement, interactive programs (vim, htop), resize. Claude Code runs natively in Linux.
MSYS2-based POSIX shell. Most terminal features work. Some interactive programs may have limitations. Suitable for most Claude Code workflows.
Windows native pseudo-console API (Windows 10 1903+). Works without WSL or Git Bash, but some ANSI escape sequences behave differently. Claude Code must be on the Windows PATH.
Raw stdin/stdout pipes with no terminal emulation. Output appears but interactive features (prompts, colors, cursor) may not render correctly. Install WSL or Git Bash to move to a higher tier.
sessionforge status to see which tier your machine is currently using.Service Management
The agent runs as a Windows Service, which means it starts automatically on boot and runs in the background regardless of who is logged in.
Common service commands
| Command | Description |
|---|---|
sessionforge service status | Show service health and uptime |
sessionforge service start | Start the agent service |
sessionforge service stop | Stop the agent service |
sessionforge service restart | Restart the agent service |
sessionforge service install | Register the Windows Service (requires Admin) |
sessionforge service uninstall | Remove the Windows Service registration |
Viewing logs
The agent writes detailed logs to a file in your user profile. This is the first place to look when troubleshooting startup issues.
To tail the log in PowerShell:
Firewall & Network
The SessionForge agent does not require any inbound firewall rules or port forwarding. It connects outbound to the SessionForge cloud, and the browser connects to that same cloud relay — your machine is never exposed to the public internet.
Connection model
Required outbound access
HTTPS (port 443) to sessionforge.dev and *.sessionforge.dev
Inbound rules needed
None. No ports need to be opened on your firewall or router.
Windows Firewall
Windows Firewall may prompt you to allow the agent on first run. Click Allow to permit outbound connections.
Helper Process
On Windows, the agent uses a helper process to bridge between the background Windows Service and the interactive terminal environment needed to create sessions.
When a session starts, you may briefly see a sessionforge.exe process appear in Task Manager. This is normal and expected — it is the helper creating the terminal session on your behalf. It exits automatically when the session ends.
To hand off a Windows session to a teammate, see Session Handoff ↗.