Troubleshooting

Gatekeeper blocks the app

Problem: macOS refuses to launch the app on first open, saying it is from an unidentified developer.

Release builds are self-signed, not notarized, so this is expected.

Recommended: right-click or Control-click Justty.app → Open → Open again. Once is enough.

Alternative:

xattr -dr com.apple.quarantine /path/to/Justty.app
open /path/to/Justty.app

Confirm the release signature:

codesign -dv --verbose=4 /path/to/Justty.app
# expect Authority=Justty Self-Signed

Homebrew installs clear quarantine automatically. See Homebrew Tap.

Ghostty packages fail to resolve, or the submodule is missing

Problem: the build fails on Vendor/libghostty-spm.

You cloned without submodules:

git submodule update --init --recursive

Then reopen justty.xcodeproj and build the justty scheme.

Stale libghostty after a submodule bump

Problem: the binary framework looks wrong after updating Vendor/libghostty-spm.

Clean DerivedData for the project, or Product → Clean Build Folder in Xcode, then rebuild.

Shells fail, or there is no PTY

Problem: tabs open but no shell starts.

The app sandbox must stay off (ENABLE_APP_SANDBOX = NO). JusTTY uses Ghostty's .exec backend to spawn a real login shell, and enabling the sandbox breaks that.

This matters only when building from source; release builds already have it off. See Architecture.

Still stuck#

Open an issue at github.com/0x96f/justty with your macOS version, how you installed, and what you see.