Installation

Install with Go

The simplest option if you already use Go. Requires Go 1.26 or later and a C compiler for runtime plugins (GCC on Linux, Xcode Command Line Tools on macOS).

$mkdir -p "$HOME/.local/bin"
$GOBIN="$HOME/.local/bin" go install github.com/gox-lang/server/cmd/gox@latest

GOX is installed for your user in ~/.local/bin. Complete the one-time PATH setup below, then open a new terminal and run gox version.

$gox_path_line='export PATH="$HOME/.local/bin:$PATH"'
$for gox_profile in "$HOME/.profile" "$HOME/.bashrc" \
$    "${ZDOTDIR:-$HOME}/.zshrc" "${ZDOTDIR:-$HOME}/.zprofile"; do
$    touch "$gox_profile"
$    grep -Fqx "$gox_path_line" "$gox_profile" ||
$        printf '\n%s\n' "$gox_path_line" >> "$gox_profile"
$done
$for gox_profile in "$HOME/.bash_profile" "$HOME/.bash_login"; do
$    if [ -f "$gox_profile" ]; then
$        grep -Fqx "$gox_path_line" "$gox_profile" ||
$            printf '\n%s\n' "$gox_path_line" >> "$gox_profile"
$    fi
$done
$export PATH="$HOME/.local/bin:$PATH"

 # Complete the PATH setup, then open a new terminal.
$gox version

curl

One command will download and run the official installer. It will detect your system and architecture, verify the binary checksum and configure your persistent user PATH.

$curl -fsSL https://gox-lang.dev/install.sh | sh

Close this terminal and open a new one before continuing.

$gox version

The installer configures your PATH for future terminals, but cannot change the terminal where you ran it. This is normal: close that terminal, open a new one, then run gox version.

npm

Requires Node.js 20 or newer. Install the official package globally to make the gox command available through npm. The installer downloads the binary for your system from GitHub Releases and verifies its checksum.

$npm install -g @gox-lang/cli --ignore-scripts=false --foreground-scripts
$gox version

Installation scripts must be enabled. These flags enable scripts and show installation progress. Your npm global command directory must be on PATH.

$npm rebuild -g @gox-lang/cli --ignore-scripts=false --foreground-scripts

$npm install -g @gox-lang/cli@latest --ignore-scripts=false --foreground-scripts

Homebrew

Install GOX on macOS or Linux with Homebrew, on Intel/AMD x64 or ARM64. The official tap downloads the binary for your system from GitHub Releases and verifies its SHA-256 checksum.

$brew install gox-lang/tap/gox
$gox version

Homebrew must already be installed and available on your PATH. It makes gox available through its command directory. To run projects, macOS needs Xcode Command Line Tools; Linux needs GCC and development headers. On Windows, use WSL.

$brew update
$brew upgrade gox-lang/tap/gox

$brew uninstall gox-lang/tap/gox

Linux packages

Install GOX through the official signed APT or DNF repository. Packages are available for AMD64 and ARM64 and install the gox command in /usr/bin, ready to use in any terminal without changing your PATH.

$sudo apt update
$sudo apt install -y ca-certificates curl
$sudo install -d -m 0755 /etc/apt/keyrings
$sudo curl -fsSLo /etc/apt/keyrings/gox.gpg https://packages.gox-lang.dev/gox-archive-keyring.gpg
$sudo chmod 0644 /etc/apt/keyrings/gox.gpg
$echo "deb [signed-by=/etc/apt/keyrings/gox.gpg] https://packages.gox-lang.dev/apt stable main" | sudo tee /etc/apt/sources.list.d/gox.list
$sudo apt update
$sudo apt install gox-server
$gox version

$sudo apt update
$sudo apt install --only-upgrade gox-server

$sudo apt purge gox-server

$sudo tee /etc/yum.repos.d/gox.repo > /dev/null <<'EOF'
 [gox]
 name=GOX
 baseurl=https://packages.gox-lang.dev/rpm/$basearch
 enabled=1
 gpgcheck=1
 repo_gpgcheck=1
 gpgkey=https://packages.gox-lang.dev/gox-signing-key.asc
 EOF
$sudo dnf install gox-server
$gox version

$sudo dnf upgrade --refresh gox-server

$sudo dnf remove gox-server

Download a binary

GOX v0.1.9 · Choose your operating system and architecture. These are versioned downloads, not a live release feed.

AMD64 is for Intel and AMD x64 processors. ARM64 includes Apple Silicon. For WSL, download the Linux build. Native Windows binaries support the CLI and LSP, but cannot run applications requiring Go plugins.

Verify and install

Download checksums.sha256 from the same release and compare your archive’s SHA-256 with its matching entry before extracting it.

$sha256sum gox_0.1.9_linux_amd64.tar.gz
 # macOS: shasum -a 256 gox_0.1.9_darwin_arm64.tar.gz

Example for Linux AMD64, from the download directory. On macOS, replace the archive name with your selected Darwin build.

$mkdir -p "$HOME/.local/bin"
$tar -xzf gox_0.1.9_linux_amd64.tar.gz gox
$install -m 755 gox "$HOME/.local/bin/gox"

Finish with the one-time PATH setup →

GOX prepares its Go, Node.js and pnpm toolchains as needed. Initial setup requires internet access. Linux and macOS also need a C compiler for plugins.

 # Complete the PATH setup, then open a new terminal.
$gox version

Build from source

For inspecting or modifying GOX. Install Git, Go 1.26+ and a C compiler. This example checks out a stable tag for a reproducible source version.

$git clone https://github.com/gox-lang/server.git
$cd server
$git checkout v0.1.9
$go build -trimpath -o ./build/gox ./cmd/gox
$mkdir -p "$HOME/.local/bin"
$install -m 755 ./build/gox "$HOME/.local/bin/gox"

Finish with the one-time PATH setup →

To update a custom build, choose the new tag, rebuild and repeat the installation.

 # Complete the PATH setup, then open a new terminal.
$gox version

Docker

Run GOX in a container with the official image from GitHub Container Registry. It includes the verified GOX release binary and the C compiler needed for plugins. Docker selects the Linux AMD64 or ARM64 image for your machine.

$docker run --rm ghcr.io/gox-lang/server:latest version

Requires Docker Engine with Compose on Linux, or Docker Desktop on macOS or Windows using Linux containers. GOX runs inside the container; this method does not add a gox command to your host terminal.

Run your project with Compose

Save this as compose.yaml in the root of an existing GOX project.

services:
  gox:
    image: ghcr.io/gox-lang/server:latest
    user: "${GOX_UID:-1000}:${GOX_GID:-1000}"
    command: ["run", "--host", "0.0.0.0", "--port", "3000"]
    working_dir: /workspace
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - .:/workspace
      - toolchains:/var/lib/gox
    init: true
volumes:
  toolchains:

$GOX_UID=$(id -u) GOX_GID=$(id -g) docker compose up

Run the command from that same directory in a Linux or macOS shell, or in WSL. GOX_UID and GOX_GID match your user so files created in the project remain yours. Open http://localhost:3000 when the server is ready.

The project folder is shared with the container. The toolchains volume keeps downloaded tools between runs; the first start requires internet access. Stop the server with Ctrl+C.

$docker run --rm -it --init \
$  --user "$(id -u):$(id -g)" \
$  -p 127.0.0.1:3000:3000 \
$  -v "$PWD:/workspace" \
$  -v gox-toolchains:/var/lib/gox \
$  ghcr.io/gox-lang/server:latest \
$  run --host 0.0.0.0 --port 3000

$docker compose pull
$GOX_UID=$(id -u) GOX_GID=$(id -g) docker compose up --force-recreate

Install from VS Code

GOX Tools provides completion, diagnostics, formatting and themes. It can install GOX when it is missing and make it available in new terminals.

$code --install-extension gox-lang.gox-tools

Wait for GOX Tools to finish installing GOX in VS Code, then open a new terminal.

$gox version

Requires VS Code 1.91+. Existing GOX installations are respected. On Windows, open the project in WSL and install the extension there. Reopen your terminal to pick up PATH changes.

Keep GOX up to date

For direct binary installations, use gox update. If you installed with npm, Homebrew, APT, DNF or Docker, use the update instructions for that method above.

$gox update

gox run recommends available updates but does not install them. GOX Tools can coordinate updates for its managed installation. Project dependencies are updated separately.