Three ways, one foreman command

Install script (recommended)

$ curl -fsSL https://raw.githubusercontent.com/tuzlu07x/foreman/main/install.sh | bash

Homebrew (macOS, Linuxbrew)

$ brew tap tuzlu07x/foreman && brew trust --formula tuzlu07x/foreman/foreman-agent && brew install foreman-agent

npm (Node 22.12+)

$ npm install -g foreman-agent

One line. Reuses your Node 22 or 24; otherwise installs Node 22 LTS through nvm, then runs npm install -g foreman-agent. See what it does.

$ curl -fsSL https://raw.githubusercontent.com/tuzlu07x/foreman/main/install.sh | bash

Options, upgrade, uninstall

Most people never touch these.

FOREMAN_VERSION=2.3.0	Install that release instead of the latest.
FOREMAN_INSTALL_PREFIX=<dir>	Use a non-default global npm prefix.
FOREMAN_SKIP_NVM=1	Never bootstrap nvm; fail if no supported Node is found.
FOREMAN_REUSE_ANY_NODE=1	Reuse a Node ≥ 22 outside the tested 22 / 24 lines.
FOREMAN_NVM_DEFAULT=1 / =0	Make Node 22 your nvm default without asking / leave your default alone.
--uninstall	Remove Foreman: the background service, its entries in your agents' configs (MCP server, Claude Code hook) and the package. Asks before deleting Foreman's data.
--uninstall --purge	The same, and delete Foreman's data without asking.

Variables go before bash, flags after bash -s --:

$ curl -fsSL .../install.sh | FOREMAN_VERSION=2.3.0 bash

The background service runs Foreman's whole gateway at every login, with no terminal open: the local daemon for your agents and Claude Code's hook, approvals to Telegram, Slack or Discord and your taps back, /foreman from chat, the daily digest and budget alerts. It is a LaunchAgent on macOS and a systemd user unit on Linux and WSL2. Without systemd (common on WSL) install says so and changes nothing. Native Windows isn't supported.

$ foreman service install     # start it now and at every login
$ foreman service status      # running? who runs the gateway? where it logs
$ foreman service uninstall   # stop it and remove the service file

With the service running, foreman start attaches to it and shows the TUI only; quitting the TUI leaves the service running. With neither running, nothing shows an approval and a call that needs one is denied when it times out. Details: docs/mcp-hub.md.

$ npm install -g foreman-agent@latest      # or: brew upgrade foreman-agent
$ foreman --version
$ foreman agent hook install claude-code   # if you use Claude Code's hook
$ foreman service install                  # if you use the service

Both commands record absolute paths, so run them again after upgrading Foreman or Node. From 2.3 on, Claude Code's hook names Foreman by absolute path and blocks the call if it can't run; re-running hook install once moves an older hook over. foreman doctor warns about a hook or service whose path is gone.

The install script does it all: it removes the background service, each agent's Foreman entries (MCP server, Claude Code hook) and the package, then asks before deleting Foreman's data. It doesn't remove a hook added to one project with --project.

$ curl -fsSL .../install.sh | bash -s -- --uninstall

By hand, in this order (the first commands need foreman). Foreman's home is left in place until you delete it; foreman doctor prints where it is.

$ foreman agent hook uninstall claude-code
$ foreman service uninstall         # if you installed it
$ foreman agent list
$ foreman agent remove <id> --yes   # once per agent
$ npm uninstall -g foreman-agent      # or: brew uninstall foreman-agent

Full steps: docs/install.md.

NextQuick Start Run the setup wizard, guard Claude Code, approve from your phone, then set up your company of agents.

What the install script does

Checks the node on your PATH and reuses it when it is Node 22 or 24.
Otherwise downloads nvm's installer (pinned to v0.40.1, from the nvm-sh GitHub repository) to a temp file, runs it, and installs Node 22 LTS through nvm. No compiler or Python needed. nvm's installer adds its loader to your shell profile. With FOREMAN_SKIP_NVM=1 the script stops here instead.
Runs npm install -g foreman-agent (or the version in FOREMAN_VERSION, into FOREMAN_INSTALL_PREFIX if set).
Runs foreman --version to check the command is on your PATH, and prints the next steps.

It does not use sudo, create Foreman's home, register agents or send anything anywhere. Prefer to read it first? install.sh on GitHub, or download it, read it, then run it:

$ curl -fsSL https://raw.githubusercontent.com/tuzlu07x/foreman/main/install.sh -o install.sh
$ less install.sh
$ bash install.sh

If the script installed Node through nvm, open a new shell (or run . "$HOME/.nvm/nvm.sh") before running foreman.

Verify the install

$ foreman --version
2.3.0
$ foreman doctor   # exit 0 = all ok · 1 = warnings only · 2 = failures

On a fresh machine foreman doctor exits 1 with a few warnings (for example, no agents registered yet). That's normal. Exit 2 is a real failure. foreman --help lists every command.

First run

Create Foreman's home, run the setup wizard (LLM providers, Foreman's own model, your agents and Claude Code's hook, chat apps, integrations), then keep the gateway running at login so approvals reach your phone. The Quick Start explains each step.

$ foreman init              # identity, policy, secret store, audit database
$ foreman setup             # the setup wizard
$ foreman service install   # the gateway at every login
$ foreman start             # the terminal UI

Supported platforms

macOS	arm64 (Apple silicon), x64 — npm and binary
Linux, glibc	x64, arm64 — npm and binary
Linux, musl (Alpine)	x64, arm64 — npm only
Windows	x64, arm64 — inside WSL2

The SQLite driver ships prebuilt binaries, so nothing is compiled at install time; other platforms (FreeBSD, 32-bit ARM, …) can't open Foreman's database. Details: docs/install.md.

Install Foreman.