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).
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 |
A registry entry without an entry for the current platform causes the agent to fail to start with No binary distribution for platform: <key>. Agents distributed as npx or uvx packages are not affected — they use the registry manager directly and need no per-platform build.
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%.