Docs
GitHubBlog

Search Documentation

Search for a page in the docs

Windows

OpenAlice has two Windows paths:

  • the source install gives you the clearest logs and remains the recommended path for daily use, debugging, and reporting beta failures; and
  • the self-contained desktop beta bundles Electron Node, managed Pi, PortableGit, Bash, pinned fd/ripgrep, and the OpenAlice Workspace CLIs.

The desktop .exe is still unsigned and may be blocked by SmartScreen. Desktop packaging and updates are beta, so use the installer only if you are comfortable evaluating that path. Otherwise follow the source path below.

Desktop beta installer

Download the unsigned Windows x64 .exe

The packaged default does not require Node, npm, pnpm, Git for Windows, WSL, or a separately installed agent CLI, but it is not the most debuggable Windows path yet. After installation, let managed Pi manage access through its own login/provider flow or choose Settings → AI Provider, then create a Chat Workspace using Pi. A saved vault credential can optionally become Pi's default for new Workspaces.

The app supplies the runtime, not the model account. You may also install Claude Code, Codex, Cursor Agent, Antigravity, Grok Build, Oh My Pi, OpenCode, or Pi yourself and use its normal login/config. Follow the selected runtime's upstream Windows instructions; the POSIX one-line install hints shown on other platforms are not Windows setup commands.

Desktop updates remain beta. The app shows download progress, then named shutdown and installer-handoff stages. Restart and update stops managed services, releases the Runtime lock, runs the assisted NSIS replacement silently, and should reopen OpenAlice automatically. The app may remain closed for up to a minute; do not launch another copy during that handoff.

The 0.89 updater also takes over residual processes from older installations and bypasses legacy long-path uninstallers before replacement. If the handoff cannot start, OpenAlice keeps or relaunches the current version and reports the diagnostic log. If the old version returns after an incomplete update, the next launch identifies the target that failed and offers retry or manual installation. User data remains outside the app bundle under the selected OpenAlice home.

Source install

Requirements

Install these first:

Install pnpm with:

npm install -g pnpm

Or use Corepack if you already prefer it:

corepack enable
corepack prepare pnpm@latest --activate

Clone and install

Open PowerShell, then run:

git clone https://github.com/TraderAlice/OpenAlice.git
cd OpenAlice
pnpm install

Run OpenAlice

pnpm dev

The dev orchestrator prints the URLs it picked. Open the UI URL, usually:

http://localhost:5173

Trust the URL printed by the terminal if the port auto-bumps.

Runtime-managed access

OpenAlice does not run the model loop inside its own backend. It starts native agent CLIs inside workspaces.

For Claude Code:

claude

Complete the login flow once. If you use Codex:

codex login

You can also add API-key credentials later in Settings -> AI Provider.

Do you need WSL or Git Bash?

Usually, no.

Built-in workspace templates bootstrap on OpenAlice's Node process and bundled git path. They do not need bash, WSL, or system git at runtime. A source checkout discovers Git Bash from the Workspace-shell preference, PATH, or standard Git for Windows locations.

Install Git for Windows for source-based Workspace terminals and scheduled shell work. WSL2 is not required. A third-party template may still bring its own additional shell assumptions.

Troubleshooting

PowerShell cannot run pnpm — Check your execution policy or use a normal terminal profile that can run global npm binaries.

A port is already in use — pnpm dev probes and auto-bumps ports. Open the URL it prints.

SmartScreen blocks the .exe — Use the source path above. The package is self-contained, but Windows signing/distribution is still beta.

The app fails after a desktop update — Read the native error's last Alice output and diagnostic log path. Retry from Settings or install the latest .exe again; use the source path when you need the clearest logs. Your workspaces and settings live outside the app bundle.

Agent authentication fails — Run claude or codex login directly in the same Windows user account, complete login, then restart pnpm dev.

A Workspace or scheduled run cannot find Bash — Open Settings → General → Workspace shell (Windows). Use Automatic with Git for Windows installed, or select an absolute bin\bash.exe path. An invalid custom path fails loudly instead of silently falling back.

Next Steps