Installation

fx supports macOS and Linux on x86_64 and arm64. The installer needs curl or wget, plus tar.

Install the latest release

Run the installer:

https://fx.sh/setup.sh is the canonical installer. Nothing else needs to be trusted to install fx.

Review the installer before running it

Piping a script to a shell runs whatever the server returns. If you or your organization require a review first, download it, read it, and run the copy you read:

What the script does, in order: detect your platform, resolve the latest published version, download and unpack that release archive, install the binary, and offer to put it on your PATH. Specifically:

• It installs to ~/.local/bin. Set FX_INSTALL_DIR to install somewhere else.
• If the install directory is not already on your PATH, it appends a PATH line to your shell profile: ~/.zshrc, ~/.bash_profile or ~/.bashrc, or ~/.config/fish/config.fish. It skips that edit when the directory is already mentioned in the file.
• Release archives are downloaded over HTTPS from Vercel's release storage. The script does not check a signature or a published checksum, so an audited install should read the script, fetch the archive it names, and verify that artifact with your own process.

For automation, pass a version so a run is reproducible instead of tracking the latest release:

Put fx on your PATH

If your shell cannot find fx after installing, add the install directory to the current shell:

Restarting the shell picks up the line the installer added to your profile.

Verify the install

Print the installed version:

Run local health checks:

fx doctor reports the workspace, configuration, authentication, resolved startup settings, local session state, and Git integrations without starting an agent turn.

Upgrade

Upgrade to the latest release on the selected channel:

Add --channel stable or --channel dev to select and remember a release channel.

The interactive shell also reports available updates and can install them in place. Set FX_AUTO_UPGRADE=0 to skip automatic upgrade checks for one process.

When an automatic update is installed, the footer offers ctrl+g to reload. Press it with an empty composer and no active response or focused view. fx relaunches the installed binary and resumes the current session. If the session cannot be handed off safely, fx stays open and explains what must finish or close first.

Build from source

Building from source requires Zig 0.16 or newer. Clone the repository, build a release binary, then verify it:

1git clone https://github.com/vercel-labs/fx.git2cd fx3zig build -Doptimize=ReleaseSafe4./zig-out/bin/fx --version

Optional tools

• gh is required only to publish drafts with fx pr --create or fx issue --create.
• tmux is required only for the terminal end-to-end tests described in the repository's contributing guide.

Next, authenticate and follow the quick start. If the install did not work, see Troubleshooting.