Install Golem

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.

Before you start#

• A workspace key. In the console, 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#

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.
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: 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:

$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.

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.

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:

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#

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:

Installer options#

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

Upgrading#

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:

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:

$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.