# Install Golem

> Put the Golem agent on a Mac, Linux or Windows machine with one line, check it with golem doctor, and take it all back with one command.

You install the Golem agent once per machine. The installer downloads it, checks it, enrolls the machine into your workspace, starts it as a background service and connects the coding agents it finds. Then you restart those agents and run `golem doctor`.

To roll it out across many machines at once, read this page first, then [Roll out to a fleet](/fleet).

## Before you start

- **A workspace key.** In the [console](https://app.golem.team), open **Deploy → Install** and choose **Install Golem**. It creates an enrollment key (it starts `glk_`) and shows the install command for macOS and Linux and for Windows, with the key already in it. The key is shown once, so copy the command then.
- **A supported machine.** macOS or Linux on x86-64 or Arm, or 64-bit Windows. Windows on Arm runs the x86-64 build under emulation.
- **`curl` or `wget`** on macOS and Linux. On Windows, PowerShell 5.1 or later, run as administrator.
- **Your own account, not root.** On macOS and Linux the agent runs as the person who uses the machine. Run the installer as that person, without `sudo`.

## Install on macOS or Linux

```bash
curl -fsSL https://app.golem.team/install.sh | GOLEM_WORKSPACE_KEY=glk_... sh
```

In order, it:

1. Downloads the release for this machine and checks its SHA-256 against the release's checksum list. A mismatch stops the install before anything is written.
2. Installs the `golem` binary. It uses `/usr/local/bin` when that is writable or already holds `golem`, and `~/.local/bin` otherwise. When that directory is not on your `PATH`, it adds one line to your shell profile, marked `# added by the Golem installer`.
3. On macOS, installs the shell jail's shim under `~/.golem/bin`. See [The shell jail](/shield#the-shell-jail).
4. Enrolls the machine with `golem join`. The key is used for this one command and is not written to any file or service configuration, so the machine never holds a credential that could enroll another one. If enrollment fails, the installer stops here and tells you why.
5. Starts a per-user background service: a launchd agent labelled `team.golem` on macOS, or a `systemd --user` unit, `golem.service`, on Linux. On Linux it also tries to turn on lingering for your user, so the service keeps running after you log out.
6. Waits for the agent to answer and confirm enrollment.
7. Connects the coding agents on the machine with `golem setup-client` (below).
8. On a Mac with Apple silicon and macOS 26 or later, sets up [the sandbox](/shield#the-sandbox): it installs Apple's `container` package, after checking its checksum and Apple's signature, and macOS asks for your password once. Skip it with `GOLEM_NO_SANDBOX=1`.

## Install on Windows

Open PowerShell with **Run as administrator** and paste:

```powershell
$env:GOLEM_WORKSPACE_KEY='glk_...'; iwr -useb https://app.golem.team/install.ps1 | iex
```

It does the same checks and enrollment, with three differences:

- The agent runs as a Windows service, `GolemWitness`, under LocalSystem, set to start automatically and to restart if it fails. That is why the installer needs administrator rights.
- The binary goes to `C:\Program Files\Golem` and is added to the machine `PATH` for new shells. The agent's state and log live in `C:\ProgramData\Golem`.
- There is no shell jail or sandbox on Windows yet.

Connecting the coding agents is per user. The installer does it for the account that ran it. If that was SYSTEM, it says so, and each person runs `golem setup-client` in their own session. See [Roll out to a fleet](/fleet).

## What it changes on the machine

`golem setup-client` adds Golem's entries to each client's own files and leaves every other entry alone. Golem's MCP servers are named `golem-witness` and `golem-context`, and both point at the agent on `127.0.0.1`. Running it again changes nothing, and it repairs only Golem's entries.

| Client | Files Golem edits | Page |
|---|---|---|
| Claude Code | `~/.claude.json`, `~/.claude/settings.json` | [Claude Code](/agents/claude-code) |
| Cursor | `~/.cursor/hooks.json`, `~/.cursor/mcp.json` | [Cursor](/agents/cursor) |
| Codex | `~/.codex/hooks.json`, `~/.codex/config.toml` | [Codex](/agents/codex) |
| Others | each client's own hook and MCP files | [Copilot](/agents/copilot), [Gemini CLI](/agents/gemini-cli), [Devin](/agents/devin), [Antigravity](/agents/antigravity), [OpenClaw](/agents/openclaw), [Hermes](/agents/hermes) |

It also gives each client it connected Golem's skills and the `/safely` and `/sandbox` commands, in that client's own skills or commands folder.

Clients you install later are picked up too. The agent checks for new clients on a schedule set in the console and connects them, unless you removed Golem from that machine's clients with `golem setup-client --remove`.

The other files the installer writes:

| What | macOS and Linux | Windows |
|---|---|---|
| Binary | `/usr/local/bin/golem` or `~/.local/bin/golem` | `C:\Program Files\Golem\golem.exe` |
| Service | `~/Library/LaunchAgents/team.golem.plist` or `~/.config/systemd/user/golem.service` | service `GolemWitness` |
| Settings | `~/.config/golem/golem.env`, readable only by you | the service's environment |
| State and keys | `~/.golem` | `C:\ProgramData\Golem` |
| Log | `~/.golem/logs/golem.log` | `C:\ProgramData\Golem\logs\witness.log` |

The agent listens on `127.0.0.1` only, on port 39393 unless you change it.

## Restart your agents

Claude Code, Cursor, Codex and the rest read their hooks and MCP servers when they start. Quit and reopen each one, and start a new session in each terminal agent. Until you do, they run without Golem.

## Check it with golem doctor

```bash
golem doctor
```

It checks the install end to end and prints the command that fixes each problem. Among other things it checks that:

- the agent is running and its service is registered;
- the machine is enrolled, with a key that persists across restarts;
- every client entry points at the port the agent actually listens on, and every hook command exists;
- Codex has approved Golem's hooks, when Codex is installed;
- for each agent that has run, its tool calls reached the hooks, so rules could act on them;
- recorded events are being delivered, and the agent is up to date.

It exits non-zero when anything fails, and `golem doctor --json` gives the same in a form a script can read. The machine also appears in the console under **Hosts, Groups & Profiles** once it has enrolled.

Other commands you may want:

| Command | What it does |
|---|---|
| `golem status` | Version, host, wiring, identity and anything not yet delivered |
| `golem logs -f` | Follows the agent's log |
| `golem config` | Shows the settings in effect and where each came from. It is read-only: re-run the installer to change them. |
| `golem setup-client` | Connects or repairs the clients on this machine |

## Installer options

Set these in the environment of the install command. On macOS and Linux, flags go after `sh -s --`.

| Option | What it does |
|---|---|
| `GOLEM_LABELS=env=prod,team=platform` | Linux and Windows: tags the machine so a group's label rule can claim it. Also `--labels=`. See [Roll out to a fleet](/fleet). |
| `GOLEM_AGENT_PORT` | The local port the agent listens on. Default 39393. |
| `GOLEM_AGENT_VERSION` | Installs this version instead of the latest. |
| `GOLEM_INSTALL_DIR` | Where to put the binary. |
| `GOLEM_HOST_ID` | The name the machine enrolls under. By default a machine that enrolled before keeps its name; otherwise it is the computer's name. |
| `GOLEM_NO_SERVICE=1` | Installs the binary only. |
| `GOLEM_NO_SANDBOX=1` | macOS: skips the sandbox and its password prompt. |
| `GOLEM_NO_MODIFY_PATH=1` | Prints the `PATH` line instead of adding it to your profile. |
| `--with-extensions` | Also installs the [browser extension](/agents/browser-extension) and the editor extension. `--with-browser-ext` and `--with-editor-ext` do one each; `GOLEM_WITH_EXTENSIONS=1` is the same as the flag. macOS and Linux only. |
| `GOLEM_STATE_DIR` | Windows: where the agent keeps its state. Default `C:\ProgramData\Golem`. |

## Upgrading

```bash
golem update
```

It checks the new release against its checksum, swaps the binary, restarts the service, re-runs `golem setup-client` and updates any extensions and plugins already on the machine. `golem update --version` followed by a version number installs that release, and `golem rollback` puts the previous binary back.

The agent never updates itself. When a newer release is out, it asks your coding agent, once per session, to mention it and offer to run `golem update`. Turn that notice off with **Update notice** in a profile's **Maintenance** section, if you push updates some other way.

## Uninstall

On macOS and Linux, as the same user who installed it:

```bash
curl -fsSL https://app.golem.team/install.sh | sh -s -- --uninstall --purge
```

It removes Golem's hooks and MCP entries from every client, then stops and removes the service, the binary, the shell jail's shim and the `PATH` line. `--purge` also removes the agent's local state in `~/.golem` and its settings in `~/.config/golem`. Without it, those stay, so a reinstall comes back as the same host.

On Windows, from PowerShell run as administrator:

```powershell
$env:GOLEM_UNINSTALL='1'; $env:GOLEM_PURGE='1'; iwr -useb https://app.golem.team/install.ps1 | iex
```

What uninstalling leaves behind:

- **Claude Code's skills and commands.** Golem's files in `~/.claude/skills` (folders named `golem-fleet`, `golem-sandbox`, `safely` and `sandbox`) and `~/.claude/commands` (`safely.md` and `sandbox.md`) stay, because the Cursor CLI reads them too. Delete them by hand if you want them gone. Other clients' Golem skills are removed.
- **Apple's `container` package** and the sandbox's images, on a Mac that had the sandbox.
- **Other people's client entries on Windows.** The uninstaller removes the client entries of the account that runs it. Run `golem setup-client --remove` in each person's session first, before the binary is gone.
- **The machine in the console.** It stays listed, with its signed history. Revoke its key from the host's page if it should never report again.

To keep the agent but disconnect every client on a machine, run `golem setup-client --remove`. It also stops the agent putting the entries back.