Install GitGhost Desktop

This guide is for developers who want to run local coding agents and connect their work to GitGhost projects.

Before You Start

You need:

• A GitGhost account.
• Git installed on the computer.
• At least one supported coding-agent runtime if you want to run an agent locally.
• Permission to access any GitGhost repository you plan to clone or connect.

Agent vendor authentication is separate from GitGhost authentication. Signing in to GitGhost does not sign you in to Codex, Claude Code, Cursor, Gemini CLI, OpenCode, or Copilot CLI.

Download The Correct Package

1. Open gitghost.ai on the target computer.
2. Find Download the desktop app near the top of the home page.
3. Sign in when prompted.
4. Confirm that the detected operating system is correct.
5. Download the current preview package.

GitGhost serves the installer from a first-party authenticated URL. You do not need access to the private source repository or a GitHub account.

Platform	Package	Notes
macOS Apple Silicon	.dmg	Install the app as /Applications/GitGhost.app. Current preview builds require explicit installation confirmation until Developer ID signing and notarization are enabled.
Windows x64	.exe	Current preview builds may show Windows SmartScreen until Authenticode publisher signing is enabled.
Linux x64	.AppImage	Use this package when you want automatic in-app replacement and rollback. Keep it in a writable user-owned folder.
Debian/Ubuntu x64	.deb	Use the system package installer or apt; later updates remain system-package installs. Do not disable the Electron sandbox.

Install On macOS

1. Open the downloaded DMG.
2. Drag GitGhost into Applications.
3. Quit an older GitGhost version before replacing it.
4. Open GitGhost from Applications.
5. Review the macOS confirmation carefully. Do not disable Gatekeeper or remove quarantine as a workaround.

The preview targets Apple Silicon and macOS 13 or later.

Install On Windows

1. Close GitGhost if it is running.
2. Open the downloaded EXE installer.
3. Review any Windows publisher warning before continuing.
4. Finish the per-user installation and launch GitGhost.
5. Install or repair Git for Windows with Git Credential Manager if repository cloning reports that the credential manager is missing.

The current installer is integrity-verified by GitGhost but does not yet display an Authenticode publisher identity.

Install On Debian Or Ubuntu

Use the graphical package installer, or run:

sudo apt install ./GitGhost-<version>-linux-x64.deb

GitGhost needs an unlocked Secret Service keyring, such as GNOME Keyring, to store credentials. The application does not fall back to plaintext credential files.

Never start GitGhost with --no-sandbox to work around a launch problem.

Sign In With The Device Flow

1. Open GitGhost.
2. Select Sign in.
3. Open the displayed GitGhost authorization page.
4. Confirm that the browser code matches the desktop code.
5. Approve the device with the intended GitGhost account.
6. Return to the app and confirm the status bar shows Connected.

Passwords and provider credentials do not enter the desktop renderer. The native process stores the GitGhost device credential in the operating-system keyring.

Choose Account Sharing

Open Settings > Account to choose how the desktop and terminal CLI authenticate.

Choice	Behavior
Separate desktop sign-in	Desktop and terminal CLI keep independent GitGhost device sessions. Signing out of one does not sign out the other.
Use existing CLI sign-in	Desktop explicitly shares the CLI profile stored in the OS keyring. Signing out of the shared profile also affects terminal CLI access.

The desktop UI never receives the raw token in either mode.

Confirm The First Run

The Dashboard presents one three-step path:

1. Sign in to authorize this desktop.
2. Connect a repository by opening a local folder or cloning a GitGhost project.
3. Run one agent task and open its captured result.

The primary button changes with your current state, so it asks only for the next missing step. Workspace tools stay out of the main navigation until a repository is open.

After opening a repository, select Agents to see which coding tools are installed. A detected runtime can still require a vendor login, API credential, supported account, or a setup repair.

Update The App

GitGhost checks for updates after launch and every six hours while it is running. A release is offered only when it matches the channel selected under Settings > Updates:

• Stable receives production releases only.
• Preview receives prerelease builds and can later move to the corresponding stable release.

When a compatible update is available, GitGhost shows an in-app prompt. Select Update now to download and verify it in the background, or Later to keep working. When preparation finishes, select Restart and update. GitGhost closes, replaces the installed application, reopens on the new version, and removes its temporary update files.

The update path validates the GitGhost release manifest, expected file size, SHA-256 digest, and operating-system publisher identity before replacement. A failed download or verification leaves the current application untouched and exposes a retry action. GitGhost removes cancelled downloads, stale staging folders, previous updater artifacts, and a completed Linux rollback image after the new process remains healthy. A canonical macOS launch also ejects legacy GitGhost installer volumes backed by its private update cache; it never ejects the volume it is currently running from or removes a manually downloaded installer.

Automatic Update Support

Installation	Automatic behavior
Developer ID-signed and notarized /Applications/GitGhost.app	Downloads a signed ZIP through a private loopback feed, asks for restart consent, and lets the macOS updater replace and relaunch the canonical app.
Authenticode-signed Windows installation	Verifies the configured publisher, stages the NSIS update, then replaces and restarts GitGhost after consent.
Linux AppImage	Stages a verified AppImage beside the current image, atomically replaces it after exit, and automatically restores the previous image if the new process does not stay healthy.
Unsigned preview, macOS app outside /Applications, Linux DEB, or unsupported package	Verifies the download but keeps installation as an explicit manual fallback. It never silently weakens signature or location requirements.

Preview installation

Current macOS and Windows preview builds are not production publisher-signed. They can discover and verify an update, but automatic replacement remains disabled. Production automatic updates activate only for Developer ID-signed and notarized macOS builds or Authenticode-signed Windows builds. Do not bypass Gatekeeper or SmartScreen to simulate that trust.

Settings > Updates remains available to check immediately, change channels, retry a failed download, or reveal a verified manual installer when automatic replacement is unavailable.

Next Step

Open Projects And Repositories to add your first local or GitGhost project.