Braide runs as a Next.js server plus an optional Electron shell. The same codebase targets macOS, Linux, and Windows across both x86_64 and arm64.
| OS | Architecture | Notes |
|---|---|---|
| macOS | arm64 (Apple Silicon) | Primary development platform |
| macOS | x86_64 (Intel) | |
| Linux | arm64 | |
| Linux | x86_64 | |
| Windows | arm64 | Requires Windows 10 1809+ (ConPTY) and PowerShell 5.1+ |
| Windows | x86_64 | Requires Windows 10 1809+ (ConPTY) and PowerShell 5.1+ |
The embedded terminal and the session exec endpoint spawn commands through a platform-default shell.
| Platform | Default | Override |
|---|---|---|
| macOS / Linux | $SHELL → /bin/sh | Set SHELL in the environment |
| Windows | %ComSpec% → cmd.exe | Set ComSpec in the environment |
On Windows, $SHELL is ignored even if set (MSYS/Git Bash leaks /usr/bin/bash, which cmd.exe cannot execute).
node-pty runs in an isolated pty-host child process on every platform, so a hung or crashing shell spawn degrades the terminal gracefully instead of freezing the app. On Windows arm64 the terminal uses node-pty's bundled ConPTY (conpty.dll) automatically — a full-fidelity, modern ConPTY. It's preferred over the system ConPTY, which on arm64 throws an uncaught AttachConsole failed on every kill (node-pty forks a console-list agent only on the system path). Windows x64 uses node-pty's default (system ConPTY). No configuration is required. The backend in effect is recorded per session in the pty-host diagnostics (useConpty / useConptyDll) — see Logging. To force a specific backend, set BRAIDE_PTY_CONPTY.
Agents that ship prebuilt binaries use a canonical <os>-<arch> key in their registry entry:
Node process.platform / process.arch | Binary key |
|---|---|
darwin / arm64 | darwin-aarch64 |
darwin / x64 | darwin-x86_64 |
linux / arm64 | linux-aarch64 |
linux / x64 | linux-x86_64 |
win32 / arm64 | windows-aarch64 |
win32 / x64 | windows-x86_64 |
An agent is compatible with the current platform when it offers a platform-agnostic launcher (npx or uvx) or a binary keyed for the running <os>-<arch>. Compatibility is computed on the backend (from the platform key above) and sent to the settings UI: incompatible agents still appear in the Agents list, but they are flagged Unsupported on this platform and their enable toggle and settings (cog) button are disabled, so you cannot start one that has no build for your machine. Agents distributed as npx or uvx packages are never affected — they need no per-platform build.
The older start-time guard — No binary distribution for platform: <key> — remains as a backstop, but with the list-level gate you should not normally be able to reach it for a binary-only agent.
Agent binary archives are unpacked in-process using pure-JavaScript libraries — no unzip, tar, or gunzip binary is required on PATH.
| Format | Handled by |
|---|---|
.zip | yauzl |
.tar, .tar.gz, .tgz | tar |
.gz (single file) | Node's built-in zlib.createGunzip |
Entries that try to escape the destination directory (zip-slip) are rejected before any bytes are written.
Unix file permissions recorded in .zip archives (the executable bit on shipped binaries and scripts) are preserved on extraction. Zips produced on non-Unix hosts that carry no mode information fall back to the filesystem default.
The terminal process list shows descendant processes for each open terminal. Enumeration uses platform-native tooling:
| Platform | Tool |
|---|---|
| macOS / Linux | ps -o pid=,ppid=,command= -g <pid> (process group) with a --ppid <pid> fallback |
| Windows | `powershell.exe -NoProfile -NonInteractive -Command "Get-CimInstance Win32_Process ... |
On Windows each refresh spawns a short-lived PowerShell process; expect ~100-200 ms of latency on cold start. If PowerShell is unavailable the list falls back to empty rather than failing.
~Typing ~/.braide (or ~\.braide) into the BRAIDE_HOME field in the Electron desktop app's settings is expanded to your home directory at save time — ~ is a shell-ism that neither Windows' path APIs nor Node's fs module expand on their own. The BRAIDE_HOME environment variable, on the other hand, is consumed verbatim; pass an absolute path.
Paths returned by Node filesystem APIs use the native separator (\ on Windows, / elsewhere). Paths returned by git ls-files, ACP tool calls, and the worktree diff API use forward slashes regardless of OS. Client-side components that receive a path from an ambiguous source (e.g. a directory picker that round-trips through the filesystem API) use a small helper that splits on / and \ alike.
Git output is parsed with \r?\n splits to tolerate core.autocrlf=true on Windows. Session event logs (NDJSON) are always written with \n and parsed likewise.
process.platform and exec; cross-platform behaviour in the wild may surface issues that the unit tests do not.cmd.exe unless you override %ComSpec%.