# Installation Maistik Forge ships as a single Go binary named `forge`. The same binary runs on macOS, Linux, and Windows. ::: info What Forge is (and is not) Forge **configures** the AI coding agents you already have. It is not an agent installer and not a hosted service. Local secrets stay local: API keys are read from your environment only and are never persisted. Forge does send anonymous usage and error telemetry — see [Telemetry](#telemetry) below. ::: ## Telemetry Forge sends anonymous usage and error telemetry to GitLab Observability, on by default. What's sent, every CLI invocation: - Command name (e.g. `init`, `implement`, `review`) - Forge version, OS, and architecture - A random install ID (a UUID generated once on first run and stored in `~/.forge/state.json`) — not tied to your name, email, or IP - On failure: a best-effort-redacted error message (file paths are stripped) Never sent: source code, file contents, repository names or contents, prompts, model output, API keys, or anything else from your project. Your AI coding agent's model calls and conversations are never touched by Forge, telemetry or otherwise. You'll see a one-time notice printed the first time you run any `forge` command — on `init`, or on whatever command runs first after upgrading from a version that predates telemetry. Opt out at any time: ```bash export FORGE_NO_TELEMETRY=1 ``` ## Requirements Forge itself needs, at runtime: - **git**, **curl**, **Node ≥ 18**, and **npm** — required. - **Homebrew** — optional (macOS). Some features shell out to external tools: `forge memory` / `forge recall` use the **Engram** binary, and the `graphify` codebase-memory provider needs its own tooling. Both degrade gracefully when absent, but the feature will not work without them. ## Install the binary ::: warning An active license is required Maistik Forge Kit is proprietary software. Binaries are distributed to licensed customers through a private release repository. Buy a license on the [pricing page](/pricing), giving the GitHub username of every developer who needs access, and those accounts are added after purchase. A Scoop bucket and `curl | sh` one-liners are **not yet published**. ::: ### Homebrew (macOS and Linux) Forge also publishes a private Homebrew tap, as an alternative to downloading an archive by hand below. Like everything else in this section, it requires an active license: set `HOMEBREW_GITHUB_API_TOKEN` to a token from a GitHub account with collaborator access to the release repository — the Homebrew equivalent of the `GITHUB_TOKEN`/`GH_TOKEN` that `scripts/install.sh` reads (get access at [maistik.studio](https://maistik.studio)). ```sh export HOMEBREW_GITHUB_API_TOKEN= brew tap maistik-studio/forge https://github.com/Maistik-Studio/forge-kit brew install forge ``` `brew upgrade forge` picks up new releases the same way. ::: warning `brew install forge` without the tap installs the wrong package `forge` is also the name of an unrelated formula in `homebrew-core` ([arrayfire/forge](https://github.com/arrayfire/forge), a C++ visualization library with no CLI). If you skip `brew tap maistik-studio/forge ...` first — or the tap silently fails because `HOMEBREW_GITHUB_API_TOKEN` isn't set, since the release repository is private — `brew install forge` falls back to that unrelated `homebrew-core` formula. It installs without error, but leaves you with no `forge` executable at all. Run the tap command and check its output before installing. To remove any doubt, install fully qualified instead: ```sh brew install maistik-studio/forge/forge ``` If you already hit this, `brew uninstall forge` removes the wrong package, then re-run the two commands above in order. ::: ### Download a release Once your account has access, open the release repository, pick the latest release, and download the archive for your platform: github.com/Maistik-Studio/forge-kit/releases Archives are named by platform and architecture, and every release ships a `checksums.txt` alongside them. ```sh # macOS (Apple silicon), adjust the archive name to the release you downloaded tar -xzf forge_Darwin_arm64.tar.gz sudo mv forge /usr/local/bin/forge ``` ```sh # Linux (x86_64) tar -xzf forge_Linux_x86_64.tar.gz sudo mv forge /usr/local/bin/forge ``` On Windows, extract the `.zip` and put `forge.exe` on a directory in your `PATH`. ::: tip Pro tip: stop needing `sudo` for every install `/usr/local/bin` is owned by `root` on a stock macOS/Linux install, which is why `mv`/`upgrade` need `sudo` above. Take ownership once and every future install, upgrade, or Homebrew-style operation into that directory stops asking: ```sh sudo chown -R $(whoami):admin /usr/local/bin ``` (On Linux, swap `admin` for your primary group, typically `$(whoami)` or `staff`.) Do this only on a single-user machine you control — on a shared or managed system, keep `/usr/local/bin` root-owned and use `sudo` per command instead. ::: ### Verify the download Every release publishes `checksums.txt`. Check your archive against it before running anything: ```sh shasum -a 256 -c checksums.txt --ignore-missing ``` ::: details Why bother checking a checksum? A **checksum** is a short fingerprint calculated from a file's exact contents — change even one byte, and the fingerprint changes completely. Comparing the checksum you calculate locally against the one Forge publishes confirms the file you downloaded is *exactly* the one that was released: not corrupted in transit, and not tampered with along the way. It takes one command and costs nothing to skip — until the one time it matters. ::: ### Keeping up to date Once the binary is on your PATH, Forge updates itself from the same release channel: ```sh forge update # report what is available forge upgrade # replace managed tool binaries in place ``` ![forge update and forge upgrade in action](/videos/installation.gif) ## Verify the install ```sh forge version # is it on your PATH? forge doctor # read-only ecosystem health check ``` `forge doctor` inspects your environment and reports problems without changing anything. To also smoke-test the binary end to end: ```sh forge doctor --selftest ``` ## Configure your agents Installing the binary does not touch your agents yet. To detect and configure the agents you already have: ```sh forge init # scaffold .forge/ and pick agents (wizard, or --yes) forge install # write the Forge command set into your agents ``` `forge install` detects installed agents automatically. It backs up any existing agent configuration first, then writes the Forge command set. The operation is idempotent: running it again converges to the same state. Common flags: ```sh forge install --scope workspace # configure for this project only forge install --agents claude,cursor # limit to specific agents forge install --dry-run # preview changes, write nothing ``` | Flag | Meaning | | --- | --- | | `--scope global\|workspace` | Where to write agent config. Default is `global`. | | `--agents ` | Restrict to a comma-separated set of agents. | | `--dry-run` | Show what would change without writing anything. | See [Agents](/guide/agents) for the supported agents. ![forge init and forge install onboarding wizard](/videos/onboarding.gif) ## Keeping Forge up to date ```sh forge update # check for available updates forge upgrade # apply updates to managed tools (binary-only) ``` Note that `forge upgrade` updates managed tools; it does **not** run the install/sync pipelines. Forge also checks for updates automatically on most commands; run `forge update` explicitly to control when a new release is fetched. ::: tip Pro tip: `forge upgrade` failing with "permission denied"? If the binary lives in a root-owned directory (`/usr/local/bin` on a stock install), `forge upgrade` can't write the replacement binary there. Either run the upgrade elevated: ```sh sudo forge upgrade ``` or fix ownership once so you never need `sudo` for this again — see the pro tip under [Install the binary](#install-the-binary) above. ::: ## Snapshots and cleanup Every mutation Forge makes is snapshotted automatically, so changes are reversible. There is no separate `backup` command — backups are taken before any mutating operation. ```sh forge restore --list # list snapshots forge restore latest # roll back to the most recent forge uninstall --all # remove Forge-managed config ``` ## Next steps - [Getting Started](/getting-started) — walk one change end to end. - [Introduction](/guide/introduction) — understand what Forge is and why. - [Configuration](/guide/configuration) — customize `.forge/config.yaml`.