Skip to article

Install Forge Agent CLI on Linux

Applies to Linux x64 CLI/setup 0.17.5. See release applicability. This installs the technician tool, not the customer Daemon.

The supported baseline is Ubuntu 24.04, Ubuntu 26.04 and Debian 13 on x64/glibc. Linux ARM64, Alpine/musl, macOS and formal WSL support are not claimed.

Requirements

Use an ordinary non-root account with HTTPS connectivity and:

  • CA certificates, glibc, OpenSSL, zlib and libstdc++;
  • OpenSSH client tools (ssh, scp, ssh-keygen) for device access;
  • a deliberately configured protected credential provider for login.

Secret Service additionally needs GLib/GIO and a reachable current-user D-Bus session. The self-contained CLI needs no .NET SDK/runtime installation.

Install

Download the Linux installer, archive and release manifest from Download Forge. Select matching artifacts from one release; do not combine versions from downloads made across a release change.

For the current release, run from the download directory:

chmod 700 ./forge-setup-0.17.5-linux-x64
./forge-setup-0.17.5-linux-x64 setup install \
  --archive ./forge-0.17.5-linux-x64.tar.gz --manifest ./release.json

Use the downloaded release's actual filenames. Do not run technician setup with sudo.

Setup verifies the signed package against its built-in release key, installs an immutable generation and reports path_directory. With default XDG paths:

export PATH="${XDG_DATA_HOME:-$HOME/.local/share}/forge/cli/bin:$PATH"
forge --version

Put that launcher directory in the environment of the terminal or agent runner that will use Forge. Setup does not edit shell startup files or start login.

Checksums detect changed bytes, but a checksum downloaded beside a new installer is not independent proof of its origin. Where independent bootstrap assurance is required, obtain the installer through your organization's trusted software channel. Never replace the pinned trust key to make a failing package install.

Configure protected credentials

Choose one provider in the actual user/session context that will run Forge. There is no plaintext or automatic fallback.

Existing Secret Service session

Use an existing unlocked collection. The path below is a common example; replace it if your collection has a different D-Bus path:

forge credentials configure --provider secret-service \
  --collection /org/freedesktop/secrets/collection/login
forge credentials status
forge login

Forge does not create or unlock collections or answer keyring prompts. The terminal and agent must use the same user bus/session as the collection.

Provisioned-key provider

For an agent runner, an administrator can provision a stable random 32-byte encryption key through an approved protected OS/service credential facility. The key encrypts the separate mutable token store; it is not itself a refresh token.

forge credentials configure --provider provisioned-key --key-file <protected-key-file>
forge credentials status
forge login

<protected-key-file> means the path to an already provisioned, protected binary key file—not literal key bytes. Do not put key bytes in commands, place an unprotected key beside its ciphertext, or weaken directory permissions to pass a check. Preserve a protected recovery method: loss of the key requires fresh login.

Both providers protect storage, not against arbitrary code running as the same user or root. Credential operations must be ready and non-prompting. Browser login, consent and MFA still require genuine authorization.

Check readiness

forge whoami
forge doctor

If the provider is locked, inaccessible or unconfigured, restore that provider in the correct session before retrying. Do not switch to weaker storage. Continue with getting started.

Update and lifecycle

forge update
forge --version

For repair with matching downloaded artifacts:

forge setup repair --archive ./forge-0.17.5-linux-x64.tar.gz --manifest ./release.json

forge setup uninstall removes the owned installation while preserving profiles, credentials and host-key pins. If also removing remembered access, run forge logout --all first. Restart agents after updates so they use the new launcher/version. A reboot ends live connections; reconnect explicitly rather than replaying interrupted commands.

With default XDG settings, configuration is under $HOME/.config/forge, mutable state under $HOME/.local/state/forge, cache under $HOME/.cache/forge, and the installation under $HOME/.local/share/forge/cli. These are product data locations, not folders to delete for routine troubleshooting.