Troubleshooting

SpecForge releases are unsigned, so every operating system asks a question the first time you run one. Here is the answer on each.

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.

macOS — the standalone binaries

The terminal UI and the headless server ship as command-line binaries, and a terminal binary has no right-click ▸ Open affordance — that dialog belongs to the Finder, and these are not launched from it. Clear the quarantine flag instead, before the first run:

xattr -dr com.apple.quarantine specforge-tui
xattr -dr com.apple.quarantine 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

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.

“Not a valid OpenSpec workspace”

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 sibling git worktrees are discovered automatically — you do not add them separately. See Workspaces.