# Install WhiteMagic

The stable Gen 2 release is the recommended daily-use channel (v9.3.4). The optional Gen 3 preview (v10.3) uses a separate binary directory and store, leaves PATH unchanged, and requires an explicit absolute executable path in client configuration. It is experimental; stable setup commands and evidence do not certify it.

Full bilingual guide: https://www.whitemagic.dev/install

## Stable Gen 2 install

Linux / macOS:

```sh
curl -fsSL "https://www.whitemagic.dev/install.sh?ref=install-md" | sh -s -- --version v9.3.4 --dir "$HOME/.local/bin" --ref install-md
```

Windows PowerShell:

```powershell
& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/lbailey94/whitemagic/v9.3.4/scripts/install.ps1'))) -Version 'v9.3.4' -Dir (Join-Path $env:LOCALAPPDATA 'WhiteMagic\bin') -Ref 'install-md'
```

Release targets: linux aarch64 (release manifest declares install gate); linux aarch64 (published asset); linux x86_64 (release manifest declares install gate); linux x86_64 (published asset); macos aarch64 (release manifest declares install gate); macos x86_64 (release manifest declares install gate); windows x86_64 (release manifest declares install gate). An install-gate declaration is release metadata, not a fresh-host installation result.

After installing, open a new terminal and run:

```sh
wm --version
wm grimoire
wm connect
```

`wm connect` previews detected client configuration. Review the proposed change; add `--write` only when you want it applied. Alternatively run `wm setup <client>` for one client. Reopen the client after changing its configuration. The local MCP server uses stdio.

## Connect a client

Choose the client tab in the human guide: https://www.whitemagic.dev/install#clients. Each configuration is documentation checked against the client's documented config shape; this is not an integration test matrix. Keep the stable server command and configuration together, and use the full executable path when required by the client.

## Optional Gen 3 preview

Linux / macOS:

```sh
curl -fsSL "https://www.whitemagic.dev/install.sh?ref=install-md" | WM_STORE="$HOME/.local/share/whitemagic/gen3-preview" sh -s -- --version v10.3 --dir "$HOME/.local/bin/whitemagic-gen3" --ref install-md --no-path
```

Preview assets: linux aarch64 (release manifest declares install gate); linux x86_64 (release manifest declares install gate); macos aarch64 (release manifest declares install gate). No Windows or Intel macOS native asset is published for the current preview. Keep its binary and store separate from stable Gen 2, do not put the preview directory on PATH, and configure clients with its expanded absolute path. Do not apply Gen 2 `connect`, `setup`, or update instructions to the preview.

Preview checks and a separate store:

```sh
"$HOME/.local/bin/whitemagic-gen3/wm" --help
"$HOME/.local/bin/whitemagic-gen3/wm" serve --help
"$HOME/.local/bin/whitemagic-gen3/wm" --store "$HOME/.local/share/whitemagic/gen3-preview" serve
```

## Observed MCP runtime profiles

Gen 2 / v9 stable curated: 9.3.4, 30 observed tools/list entries. Experimental Gen 3 profiles: cyberbrain (12 entries) and full (44 entries). These are checksum-verified Linux x86-64 handshake observations, not behavior or platform parity claims. Full records: https://www.whitemagic.dev/api/install-channels.json

## Troubleshooting and data

See the guide's [first-run checks](https://www.whitemagic.dev/install#start), [troubleshooting](https://www.whitemagic.dev/install#troubleshoot), [backup and maintenance](https://www.whitemagic.dev/install#backup), and [data boundaries](https://www.whitemagic.dev/install#disk). no usage telemetry off-device by default The default local store is not encrypted; backups, exports, replicas, and other project stores are separate copies.

## Product and evidence

- Product fit and capabilities: https://www.whitemagic.dev/whitemagic and https://www.whitemagic.dev/whitemagic.md
- Release and platform records: https://www.whitemagic.dev/api/install-channels.json
- Signatures and receipt limits: https://www.whitemagic.dev/trust
- Terms and privacy: https://www.whitemagic.dev/legal#privacy