Skip to content

Update README for release documentation #165

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
enaboapps merged 1 commit into from
Jun 18, 2026
Merged

Update README for release documentation #165

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 80 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,38 @@
# Switchify PC

Desktop companion app for Switchify Android.
Switchify PC is the Windows desktop companion for Switchify Android. It runs in the tray, accepts authenticated Bluetooth commands from paired Android devices, and turns them into mouse, keyboard, text, media, window, and status actions on the PC.

## Status
Switchify PC is early-stage Windows-first software. Expect Bluetooth and Windows packaging behavior to be the main supported path for now.

Switchify PC is early-stage Windows-first software. It is intended for local-network use with paired Switchify Android devices.
## Download

Download the latest Windows installer from GitHub Releases:

- [Latest Switchify PC release](https://github.com/switchifyapp/switchify-pc/releases/latest)

Install Switchify Android from Google Play:

- [Switchify for Android](https://play.google.com/store/apps/details?id=com.enaboapps.switchify)

The Windows installer is a per-machine installer and should be installed under `C:\Program Files\Switchify PC\` so Windows can honor `uiAccess`.

## Requirements

- Windows 10 or later.
- Bluetooth enabled on the PC.
- Switchify Android installed on a nearby Android device.
- Per-machine install under `C:\Program Files\Switchify PC\` for full `uiAccess` behavior.

## Using Switchify PC

1. Install Switchify PC.
2. Install Switchify Android.
3. Launch Switchify PC and leave it running in the tray.
4. Open Switchify Android near the PC.
5. Approve the pairing request on the PC and confirm the verification code.
6. Use the Android app to control the PC.

If the main window is closed, Switchify PC continues running from the tray. Use the tray menu to reopen it or quit.

## Development

Expand Down Expand Up @@ -49,6 +77,8 @@ npm run package:win

The package script runs `npm run build` and `npm run native:build-overlay` first, then creates an unpacked Windows artifact in `dist/win-unpacked` and a per-machine NSIS installer in `dist`.

Local packaging builds artifacts under `dist`. It does not publish a GitHub release.

## Windows uiAccess packaging

Switchify PC uses `uiAccess="true"` so the installed app can interact with elevated or higher-integrity windows for accessibility and input automation scenarios.
Expand Down Expand Up @@ -88,39 +118,72 @@ npm run package:win:verify-uiaccess

Running from `npm run dev`, `dist/win-unpacked`, AppData, Downloads, or the repo does not prove that `uiAccess` is active.

Self-signed certificates are for dev/testing only. Production users should not be asked to trust a self-signed certificate manually. Azure Artifact Signing is the preferred low-cost production signing path when eligible; traditional OV/EV code-signing certificates remain possible. Production signing configuration must come from environment variables or CI secrets, never committed files.
Self-signed certificates are for development and testing only. Production users should not be asked to trust a self-signed certificate manually.

## Bluetooth connection expectations
## Production signing

Switchify PC uses Bluetooth for PC control pairing and reconnect. The Android device must be near the PC, Bluetooth must be enabled on both devices, and the first pairing still requires approval on the PC.
Production Windows packages are signed with the Certum SimplySign code-signing certificate through `signtool`.

Paired devices reconnect over Bluetooth using the existing app-level pairing token and authenticated command flow. Local-network WebSocket control, mDNS discovery, manual IP entry, and QR connection are not part of the product path.
Required environment variables:

## Security

Bluetooth proximity is not authentication. Pairing approval and authenticated commands remain required, and pairing tokens, auth proofs, and typed text payloads must not be exposed in logs or UI.
```powershell
$env:SWITCHIFY_SIGNING_MODE = "certum-simplysign"
$env:SWITCHIFY_CERTUM_CERT_THUMBPRINT = "<certum-certificate-thumbprint>"
$env:SWITCHIFY_CERTUM_TIMESTAMP_URL = "http://time.certum.pl"
```

Please report vulnerabilities by email to owen@switchifyapp.com instead of opening public issues.
The release workflow expects the Certum certificate to be available in `Cert:\CurrentUser\My` on the Windows signing runner and the SimplySign session to be available before the release job runs.

## Release CI

Only the maintainer should publish releases.

Release builds are published from tags named `vX.Y.Z`, where `X.Y.Z` matches `package.json`.

The release workflow runs on the self-hosted Windows signing runner with the `switchify-signing` label. It:

- installs dependencies with `npm ci`
- runs `npm run typecheck`
- runs `npm test`
- verifies the Certum signing certificate
- builds native helpers
- packages the Windows x64 NSIS installer
- verifies the tag matches `package.json`
- uploads the installer and update metadata to GitHub Releases

The maintainer can publish a release by pushing an annotated tag:

```powershell
git tag v0.1.0
git push origin v0.1.0
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z
```

The release workflow builds the Windows x64 installer and uploads it to GitHub Releases. Current CI release installers are unsigned until production code signing is configured.
The workflow can also be dispatched manually by the maintainer with a `tag` input.

## Bluetooth connection expectations

Switchify PC uses Bluetooth for PC control pairing and reconnect. The Android device must be near the PC, Bluetooth must be enabled on both devices, and the first pairing still requires approval on the PC.

Paired devices reconnect over Bluetooth using the existing app-level pairing token and authenticated command flow. Local-network WebSocket control, mDNS discovery, manual IP entry, and QR connection are not part of the product path.

## Security

Bluetooth proximity is not authentication. Pairing approval and authenticated commands remain required, and pairing tokens, auth proofs, and typed text payloads must not be exposed in logs or UI.

Please report vulnerabilities by email to owen@switchifyapp.com instead of opening public issues.

## MVP smoke checklist

Use this checklist after packaging changes and before publishing any installer:

- Signed installer verifies with Authenticode.
- Installer installs under `C:\Program Files\Switchify PC\`.
- App launches from `Switchify PC.exe`.
- Tray menu opens and can show the main window.
- Main window shows Android download QR/link before a device is connected.
- Android download link opens externally in the browser.
- Bluetooth helper starts and reports a safe status.
- No QR/manual local-network connection UI appears.
- No QR/manual local-network connection UI appears for pairing or control.
- No local IP address or WebSocket address appears in Settings or troubleshooting.
- Pairing approval requests appear and can be accepted or rejected.
- Android can pair with the PC using Bluetooth and approval.
Expand All @@ -136,6 +199,8 @@ Use this checklist after packaging changes and before publishing any installer:
- Keyboard shortcut works, for example `Ctrl+C` or `Ctrl+V`.
- Media key command works, for example play/pause or volume up.
- Window control commands work, for example next app and show desktop.
- Settings > Updates can check for updates in packaged builds.
- Downloaded updates show an `Install update` action.
- Disconnect all removes active Bluetooth sessions.
- Quit exits the app, removes the tray icon, and exits the native cursor overlay helper.

Expand Down