Command-line installation

This page explains how to install the gg command line on macOS, Linux, and Windows, plus verification, auto-upgrades, and common installation issues.

The gg command line is a single executable with no installer; just put it in a directory on your PATH. It binds this machine to the team server and runs the daemon that receives tasks groups dispatch to Bots on this machine.

Mac users

On a Mac, the desktop app is recommended: it has a built-in daemon, so you don't need gg, and it stays in the menu bar after you close the window. Only one of the desktop app and gg can run on a machine.

Prerequisites

Member machines need:

• git
• Node.js 22 or later (with npm). If it's missing, the daemon installs a Node.js managed by Gonggong Space into ~/.gonggong/runtime on first run; you can also install it in advance with gg agents install node.
• Claude Code and/or Codex CLI, already signed in in the terminal. You can also install versions managed by Gonggong Space with gg agents install claude / gg agents install codex.

On first run, the daemon uses npm to install the ACP adapters into ~/.gonggong/adapters/, so the machine needs access to an npm registry (the Taobao mirror npmmirror by default; change it with gg agents mirror).

Choose the right package

Download the package from GitHub Releases or ask your admin. File names look like gonggong-<version>-<os>-<arch>:

Machine	File
Mac with Apple silicon (M1/M2/M3…)	gonggong-<version>-macos-aarch64
Mac with Intel chip	gonggong-<version>-macos-x86_64
Linux x86_64	gonggong-<version>-linux-x86_64
Linux ARM64	gonggong-<version>-linux-aarch64
Windows x86_64	gonggong-<version>-windows-x86_64.exe

Not sure which chip you have? On a Mac, click the Apple menu in the top-left corner → 「关于本机」 (About This Mac); on Linux, run uname -m (x86_64 or aarch64).

The Linux build requires glibc 2.31 or later (Ubuntu 20.04+, Debian 11+, RHEL 9+).

macOS / Linux

Put it in ~/.local/bin and rename it to gg:

mkdir -p ~/.local/bin
mv ~/Downloads/gonggong-0.1.0-macos-aarch64 ~/.local/bin/gg   # use the file name you received
chmod +x ~/.local/bin/gg

If ~/.local/bin isn't on your PATH yet, add it (zsh shown; for bash use ~/.bashrc):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Use a directory you can write to

Don't put it in a directory that needs sudo, such as /usr/local/bin. When the server publishes a new version, gg downloads it and replaces itself; without write permission, it can't upgrade.

macOS says it "can't be opened"

Files downloaded from the internet carry a "downloaded from the internet" flag, and macOS blocks running them directly. Remove the flag:

xattr -d com.apple.quarantine ~/.local/bin/gg

Files you compiled from source don't have this flag, so you can skip this step.

Windows

1. Create a folder you can write to, such as C:\Users\<you>\gonggong\.
2. Rename the exe to gg.exe and put it there.
3. Add that folder to 「系统属性 → 环境变量 → Path」 (System Properties → Environment Variables → Path), then reopen your terminal.

On Windows, the daemon looks for node.exe, claude.exe, and the *.cmd launcher scripts generated by npm in PATH, %APPDATA%\npm, and ~/.local/bin. During auto-upgrade, it first renames the running exe, then puts the new file in place.

WARNING

The Windows build has seen less testing so far. If you run into problems, report them to your admin or open an issue on GitHub.

Verify file integrity

Admins provide a SHA256SUMS file with each release. Each line is "sha256 value + two spaces + file name". Check the original file you received against it:

# macOS
shasum -a 256 gonggong-0.1.0-macos-aarch64
# Linux
sha256sum gonggong-0.1.0-linux-x86_64

# Windows PowerShell
Get-FileHash .\gonggong-0.1.0-windows-x86_64.exe -Algorithm SHA256

The output should match the corresponding line in SHA256SUMS.

Build from source

1. Install Rust (only once):

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source ~/.cargo/env
   rustup update stable

   The project uses the Rust 2024 edition and doesn't pin a toolchain version. Use the latest stable release (official release builds use Rust 1.98).

2. Install a C compiler (needed by the crypto library): on macOS run xcode-select --install; on Debian/Ubuntu run sudo apt install build-essential.

3. Build and install from the repository root:

   cargo build --release --locked -p gonggong
   mkdir -p ~/.local/bin
   cp target/release/gg ~/.local/bin/gg

Set up PATH as above. For admins building packages for all platforms in bulk, see Upgrading and releasing clients.

Check the installation

gg --version   # prints the version number if installed correctly
gg agents      # lists detection results for Node.js, Claude Code, and Codex

Then follow Bind a machine to run gg login and gg run. After binding, run gg doctor once to check the connection, git credentials, disk, and more. For all commands, see the Command reference.

If you see command not found, PATH isn't set up correctly. Reopen your terminal or check the PATH setup above.

gg opens the git GUI

The oh-my-zsh git plugin defines gg as an alias for git gui citool. Add this line to the end of ~/.zshrc and reopen your terminal:

unalias gg 2>/dev/null

To work around it temporarily, use command gg ….

Automatic upgrades

• After gg run connects to the server, if your admin has published a newer version, the daemon downloads the build matching this machine's OS and architecture in the background, verifies its sha256, and replaces itself and restarts once no tasks are running on this machine.
• Downloads go to ~/.gonggong/updates/ first and replace the current binary only after verification passes; a version that fails verification isn't retried.
• The server announces its protocol version; if the versions are incompatible, the server refuses the connection and prompts you to upgrade.
• To turn off auto-upgrade: set the environment variable GONGGONG_NO_AUTO_UPGRADE=1 before running gg run, or turn off 「自动升级」 (Auto-upgrade) in the desktop app's 「设置」 (Settings) (both use ~/.gonggong/settings.json).
• The ACP adapter versions are locked together with gg and are upgraded when gg is upgraded.

For how admins publish new versions, see Client releases and Upgrading and releasing clients.

Related pages

• Command reference
• Local data and logs
• Desktop app overview and installation
• Bind a machine