> ## Documentation Index
> Fetch the complete documentation index at: https://vibex.peatboy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform support

> Artifact formats, build methods, and verification requirements for each platform.

## Support matrix

| Platform                      | Artifacts                                                              | Key dependencies                                          |
| ----------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------- |
| Linux x86\_64                 | `.deb`, `.AppImage`                                                    | A Vulkan graphical session                                |
| Linux aarch64                 | `.deb`                                                                 | Vulkan; no AppImage (linuxdeploy cannot cross-build one)  |
| macOS aarch64 / x86\_64       | `.dmg`                                                                 | A recent macOS; **unsigned and not notarized**            |
| Windows x86\_64 / aarch64     | NSIS `.exe`                                                            | **Unsigned**; installs for the current user               |
| Android arm64                 | `.apk`, `.aab`                                                         | Android SDK/NDK, `cargo-ndk`                              |
| iOS                           | `ios-simulator.app.zip`, `xcframework.zip`                             | macOS, Xcode, XcodeGen; **simulator only, unsigned**      |
| Self-hosted Linux / container | `ghcr.io/vibex-ai/vibex-server`, `ghcr.io/vibex-ai/vibex-relay-server` | Docker or the Rust binary, multi-architecture amd64/arm64 |

<Warning>
  **Signing status is a known current limitation:** macOS and Windows installers are not code-signed, so users must allow them manually the first time they open them; iOS ships unsigned simulator builds only. When no repository key is configured, Android uses a throwaway CI key generated for each release, so **candidate versions cannot upgrade in place over one another**. Before a release, confirm whether any of this has changed.
</Warning>

## Desktop platform boundaries

The authoritative runtime owns Agents, files, Git, PTY, providers, permissions, and persistence. Keep platform differences in `apps/desktop/src/platform` or a shared facade; do not duplicate business branches in the UI.

## Release channels

A channel is a **compile-time identity**, not a runtime switch:

| Channel | Product name  | App ID                      | Data directory    |
| ------- | ------------- | --------------------------- | ----------------- |
| Preview | Vibex Preview | `dev.vibex.desktop.preview` | `desktop-preview` |
| RC      | Vibex RC      | `dev.vibex.desktop.rc`      | `desktop-rc`      |
| Stable  | Vibex         | `dev.vibex.desktop`         | `desktop-stable`  |

The channel is derived from the tag (`*-preview.*` / `*-rc.*` / plain semver). The release process asserts that the versions in the tag, `Cargo.toml`, `package.json`, and `Packager.<channel>.toml` match exactly. Overriding the channel at runtime is rejected (`release_channel_override_rejected`).

## Release workflow

`.github/workflows/release.yml` runs fully automatically on `v*` tags, and the desktop matrix covers six platform / architecture combinations:

| Platform        | Runner               | Artifact format |
| --------------- | -------------------- | --------------- |
| Linux x86\_64   | ubuntu-24.04         | `deb,appimage`  |
| Linux aarch64   | ubuntu-24.04 (cross) | `deb`           |
| macOS aarch64   | macos-14             | `dmg`           |
| macOS x86\_64   | macos-14 (cross)     | `dmg`           |
| Windows x86\_64 | windows-2022         | `nsis`          |
| Windows aarch64 | windows-2022 (cross) | `nsis`          |

Mobile builds in the same workflow: an Android APK + AAB, and the iOS XCFramework + unsigned simulator app. The release job requires **all** prerequisite jobs to succeed before it creates a release, so a partial matrix never produces a broken release.

<Note>
  The workflow currently has **no** macOS notarization or Windows Authenticode step. Until those two steps are added, installers keep carrying the platform warnings.
</Note>

## Android builds

```bash theme={null}
pnpm build:mobile:android      # Debug
pnpm package:mobile:android    # Release (unsigned)
```

Set `VIBEX_MOBILE_ANDROID_TARGETS` (space-separated) to override the Debug ABIs; Release builds `arm64-v8a` only by default.

The release workflow calls `apps/mobile/scripts/sign-android-release.sh`: APKs use `zipalign` + `apksigner`, and AABs use `jarsigner`. RC / Preview generate a throwaway `vibex-ci` key when no repository key is configured; Stable releases must configure `VIBEX_ANDROID_KEYSTORE_BASE64` and `VIBEX_ANDROID_KEYSTORE_PASSWORD`, plus the optional `VIBEX_ANDROID_KEY_PASSWORD` and the repository variable `VIBEX_ANDROID_KEY_ALIAS` (default `vibex`).

<Warning>
  Using a throwaway key means **every RC release has a different APK signature**, so users cannot upgrade in place and must uninstall before installing again. This is a known tradeoff of the current RC phase.
</Warning>

## iOS builds

```bash theme={null}
pnpm build:mobile:ios
```

Builds `VibexFFI.xcframework` and generates the Xcode project. Signing, the bundle identifier, device / simulator selection, and distribution credentials are all decided by your local Xcode process; do not commit certificates or provisioning profiles to the repository.

## Desktop packaging

```bash theme={null}
cargo install cargo-packager --version 0.11.8 --locked
pnpm prepare:pdfium
pnpm package:preview    # Or package:rc / package:stable
```

Linux packages with cargo-packager, and the PDFium runtime ships with the package on **linux-x86\_64** only. Wayland-related libraries are **not** bundled (the host ABI boundary); the host provides them.

## Automatic updates

`crates/app-update` implements signed updates:

* It discovers candidate releases from the GitHub Releases Atom feed and filters them by channel.
* It verifies the Ed25519 signature of `vibex-update.json` and the SHA-256 of the artifact, with a URL allowlist limited to release download paths.
* It checks 30 seconds after launch, then every 2 hours on RC / Preview and every 6 hours on Stable, with jitter and backoff.
* AppImage replaces itself in place (with `.vibex-backup` and `pending-install.json` crash recovery); deb, the macOS app, and NSIS launch the system installer and require a restart.
* The release pipeline stages `docs/operations/release-notes-v<version>.md` from the tagged commit as `vibex-release-notes.md`, and fails the release when the file is missing or carries no `## English` section. The desktop fetches it from the verified tag under a bounded size and a shorter timeout, and selects the section by interface language with a fallback to generic Chinese and then English.

Only builds with the public key compiled in check for updates automatically.

## Mobile lifecycle

Mobile must handle backgrounding, network switches, disconnects, and reconnects. On recovery, first fetch authoritative sessions and timelines through Remote v2, then subscribe to live events; do not overwrite authoritative state with a stale projection.

## Self-hosted deployment

Bind the services to loopback, then publish them through a controlled HTTPS reverse proxy or Tailnet Serve. Host and Origin must be validated independently, and CORS must not use `*`. The gateway exposes only protocol and health check endpoints; it serves no browser UI and no business API.

See [Self-hosted headless runtime](/docs/en/self-hosted-server) and [Self-hosted Relay](/docs/en/relay) for details.