Troubleshooting

SpecForge releases are unsigned, so every operating system asks a question the first time you run one. Here is the answer on each — plus the other things that most often need explaining: WSL2 latency, specforge-serve exposure, and workspace validation.

macOS — Gatekeeper

Gatekeeper warns on first launch. Instead of double-clicking, right-click the app and choose Open, then confirm in the dialog. macOS remembers the decision, so this is a one-time step.

If that dialog does not appear — some managed Macs suppress it — clear the quarantine flag from the installed app instead, which has the same effect:

xattr -dr com.apple.quarantine /Applications/SpecForge.app

macOS — the standalone binaries

The terminal UI and the headless server ship as command-line binaries. For these clearing the quarantine flag is the only route, not an alternative one: there is no right-click ▸ Open affordance, because that dialog belongs to the Finder and these are not launched from it. Clear the flag before the first run:

xattr -dr com.apple.quarantine specforge-tui
xattr -dr com.apple.quarantine specforge-serve

Installing the server from npm skips this entirely — a package manager does not set the quarantine attribute on what it unpacks, so there is nothing to clear. See Getting specforge-serve.

Windows — SmartScreen

SmartScreen may warn that the publisher is unrecognised. Choose More info, then Run anyway.

Windows — WebView2 on older machines

The single-file portable .exe relies on the system WebView2 runtime. It is preinstalled on current Windows; on an older machine you may need to install it manually.

The NSIS installer handles WebView2 for you. If you would rather not think about it, use the installer rather than the portable build.

Linux — .deb and .AppImage

Install the .deb with your package manager. For the .AppImage, make it executable and run it:

chmod +x SpecForge_*.AppImage
./SpecForge_*.AppImage

Windows — workspaces inside WSL2

A workspace living in the WSL2 filesystem is supported, but the \\wsl.localhost share reports no filesystem events, so updates arrive on a periodic re-scan rather than instantly. If changes seem slow to appear, that is the scan interval — tune it in Settings ▸ WSL workspaces, and see Workspaces ▸ WSL2 for how git is handled.

specforge-serve is unauthenticated

specforge-serve binds 127.0.0.1:4317 by default, which is reachable only from that machine. Passing --bind 0.0.0.0 (or another interface address) publishes it on the network without authentication — only do that on a network you trust. Run specforge-serve --help for the full flag and environment-variable reference, and see Web UI & remote access for the safe remote routes.

“Not an OpenSpec workspace”

The full message reads “not an OpenSpec workspace (no openspec/ subdirectory)”, and it means what it says: a folder is only accepted if it contains an openspec/ directory. Point SpecForge at the repository root rather than at openspec/ itself, and remember that a repository’s worktrees are discovered automatically — you do not add them separately. See Workspaces.