Central Grok Bot setup

Use this guide to install Grok Bot monitoring on every member’s cloud computer from one place. Team Setup installs the helper and hook configuration, and Team Secrets supplies the hook key. Members do not enter anything.

Grok Bot monitoring is experimental, disabled by default, and monitor-only. Runlayer has verified this installation in a production tenant with a one-member pilot group: the group’s setup script installed the helper, saved the Team Secret key, and native tool activity was recorded. Grok Bot still sends empty Bot IDs, so each tool call appears on its own. Pilot the rollout before relying on organization-wide coverage.

What is configured centrally

Component	Owner and scope
Runlayer monitoring switches	Runlayer admin, once per Runlayer organization.
Hook key	Runlayer admin creates it; Grok admin saves it once as a Team Secret.
Helper and hook registration	Grok admin, as a setup script: on a pilot group first, then in Team Setup.
Coverage verification	Confirm recorded native activity for every member in the rollout.

Grok Bot gives each member one cloud computer. That member’s Bots share it, so install once per member, not once per Bot. AI Watch or MDM on a member’s laptop does not install these cloud hooks. Team Setup and Team Secrets require Enterprise and a team administrator. Without them, repeat the single-user setup for each member. Availability of Grok Bot on a Teams plan does not imply access to Team Setup.

1. Prepare Runlayer

In Settings → Organization API Keys, create one key with only the Grok Bot Hooks permission. A Team Secret holds one value for the whole team, so every covered computer uses this key and revoking it stops uploads from all of them. Its name does not identify the member in recorded activity.
In Settings → Agent session monitoring → Cloud agent hooks, enable Grok Bot and save. Full session scanning APIs must also be enabled. Enabling these switches accepts events; it does not deploy anything.
Confirm each cloud computer can reach https://YOUR-TENANT.runlayer.com/api/v1/hooks/grok-bot/events. If Grok network controls restrict destinations, allow your Runlayer tenant.

2. Save the key as a Team Secret

In the Cursor dashboard, open Grok Bot → Team Secrets → Add Secrets. Name the secret RUNLAYER_GROK_BOT_HOOK_KEY and paste the key as its value. Cursor does not show the value again after you save it. Team Secrets reach setup scripts as environment variables only while the script runs, and Bots do not receive them directly. The installer below therefore saves the key to ~/.grokbot/runlayer_hook.key, readable only by the computer user, and the helper reads that file.

Every Bot a member runs uses the same computer user. Any of those Bots can read the key file and change the helper or hook registration. The key can only submit Grok Bot hook events, but treat recorded activity as best-effort monitoring, not a tamper-proof record.

A computer whose Team Setup comes from more than one team receives no Team Secrets. The installer then keeps a key it saved earlier. Without one, uploads stay off until the member saves the single-user RUNLAYER_GROK_BOT_HOOK_KEY secret described in Create a scoped key. The helper prefers the key file, so if that file holds a revoked key, delete ~/.grokbot/runlayer_hook.key first; otherwise uploads stop without an error.

3. Build the setup script manifest

On your administrator workstation, save the Python helper from Add the hook helper as runlayer_hook.py. Replace its COLLECTOR_URL with your tenant’s literal HTTPS URL. Never embed a key in the helper. Save the following as build_grok_manifest.py beside that file. It generates runlayer-grok-team-setup.json for the setup script editor and the same script as runlayer-grok-setup.sh for review. Neither generated file contains a credential. The installer preserves unrelated hooks, backs up the original configuration once, and registers the three native tool events verified by Runlayer. For those events, it replaces earlier Runlayer registrations, including ones from the single-user setup, so a tool call is not recorded twice. It can be rerun without duplicating anything. It leaves other events alone: if the single-user setup registered lifecycle events for a helper at a different path, remove those entries before using this installer.

import json
from pathlib import Path

helper_source = Path("runlayer_hook.py").read_text()
compile(helper_source, "runlayer_hook.py", "exec")
if "YOUR-TENANT" in helper_source:
    raise SystemExit("Set COLLECTOR_URL in runlayer_hook.py before generating.")

setup = "#!/usr/bin/env bash\nset -euo pipefail\numask 077\n"
setup += "python3 - <<'RUNLAYER_SETUP'\n"
setup += f"HELPER_SOURCE = {helper_source!r}\n"
setup += r'''
import json
import os
import shlex
import tempfile
from pathlib import Path

helper_path = Path.home() / ".grokbot" / "runlayer_hook.py"
key_path = helper_path.with_name("runlayer_hook.key")
config_path = Path.home() / ".cursor" / "hooks.json"
original = config_path.read_text() if config_path.exists() else None
config = json.loads(original) if original is not None else {"version": 1, "hooks": {}}
if not isinstance(config, dict) or config.get("version") != 1:
    raise SystemExit("Expected hooks.json version 1; inspect the existing file.")
hooks = config.setdefault("hooks", {})
if not isinstance(hooks, dict) or any(
    not isinstance(entries, list)
    or any(not isinstance(entry, dict) for entry in entries)
    for entries in hooks.values()
):
    raise SystemExit("Unexpected hooks.json shape; inspect the existing file.")

command = shlex.join(["python3", str(helper_path)])
for event in ("preToolUse", "postToolUse", "postToolUseFailure"):
    entries = [
        entry
        for entry in hooks.get(event, [])
        if "runlayer_hook.py" not in str(entry.get("command", ""))
    ]
    entries.append({"command": command, "timeout": 3, "failClosed": False})
    hooks[event] = entries

def atomic_write(path, content):
    path.parent.mkdir(parents=True, exist_ok=True)
    with tempfile.NamedTemporaryFile(mode="w", dir=path.parent, delete=False) as output:
        temporary = Path(output.name)
        output.write(content)
    try:
        os.replace(temporary, path)
    finally:
        temporary.unlink(missing_ok=True)

backup_path = config_path.with_name("hooks.json.before-runlayer")
if original is not None and not backup_path.exists():
    atomic_write(backup_path, original)
atomic_write(helper_path, HELPER_SOURCE)
key = os.environ.get("RUNLAYER_GROK_BOT_HOOK_KEY", "").strip()
if key:
    atomic_write(key_path, key + "\n")
    print("Runlayer helper installed with the Team Secret key.")
elif key_path.exists():
    print("No RUNLAYER_GROK_BOT_HOOK_KEY Team Secret; kept the saved key.")
else:
    print("No RUNLAYER_GROK_BOT_HOOK_KEY Team Secret; uploads stay off until one is set.")
atomic_write(config_path, json.dumps(config, indent=2) + "\n")
'''
setup += "\nRUNLAYER_SETUP\n"

manifest = {
    "manifestId": "runlayer-grok-monitoring",
    "entries": [{"id": "install-runlayer-hooks", "setup": setup}],
}
Path("runlayer-grok-setup.sh").write_text(setup)
Path("runlayer-grok-team-setup.json").write_text(json.dumps(manifest, indent=2) + "\n")

Run python3 build_grok_manifest.py on your workstation. Review the generated files: they should contain your tenant URL and the helper source, with no secrets. The installer requires Python 3 and runs as the member’s cloud-computer user. It does not install dependencies, download code, or print the key.

4. Pilot on a group

In Members & Groups → Groups, add a manual group that contains only the pilot members.
Open the group’s Grok Bot tab. Under Setup Scripts, create a manifest, switch the editor to JSON, paste the generated runlayer-grok-team-setup.json, and save. Group setup scripts run after the team’s setup scripts and receive the same Team Secrets.
In Grok Bot → Manage Bot Computers, recreate each pilot member’s computer so the script runs now. Recreating keeps their Bots, files, and logins. Do not use Restart all VMs for a pilot: it restarts every member’s computer.
Verify each pilot member with step 6.

5. Publish to the team

After the pilot records activity successfully:

In Grok Bot → Team Setup Scripts, create a manifest, switch the editor to JSON, paste the same runlayer-grok-team-setup.json, and save. Repeat for other Grok teams in the rollout.
Delete the pilot group’s manifest so one manifest remains to maintain.

Team Setup runs at computer startup and refreshes roughly daily. This manifest omits the optional check script, so helper and key changes reapply on refresh. Coordinate a computer recreation with the member if an immediate application is needed; running work can be interrupted. Team Setup has no fleet view of script results. Track installation and recorded activity for each member rather than treating Save as rollout completion.

6. Verify coverage for every member

Use a fresh Bot after the script runs; existing executors may cache their prior configuration. Have each member ask it to run one harmless command on their cloud computer, replacing ROLL_OUT_LABEL with a label unique to that member:

printf 'runlayer-grok-check-ROLL_OUT_LABEL\n'; stat -c %a ~/.grokbot/runlayer_hook.key; sha256sum ~/.grokbot/runlayer_hook.py

The command prints the key file’s permissions and the helper’s hash, never the key itself. For each member, record these results in the rollout inventory:

Check	Required evidence
Installation	The hash matches `shasum -a 256 runlayer_hook.py` on your workstation.
Credential	`600` shows the key file exists.
Recorded activity	Sessions → Grok Bot shows an entry whose tool input contains that member’s label, with paired tool input and output.
Grouping	A second call and a second Bot produce the expected entries in the applicable identity mode.

Every computer shares one key and Grok Bot sends no Bot IDs, so a new entry or the key’s Last used in Settings → Organization API Keys can come from any member. Only the member’s own label shows that their computer is covered. These sessions belong to the hook key rather than a member. With Session privacy enabled, they appear redacted to everyone, so checking a label means unredacting the entry, which is recorded in the audit log. When native Bot IDs are empty, expect Grok tool activity — Bot unknown, one entry per tool call. A successful test proves that member’s tested path works; it does not establish complete conversation coverage or actor attribution. The key name and rollout inventory do not fill in missing provider identity. Use the native verification and troubleshooting steps for failures. HTTP 200, an explicit allow response, and installed files alone do not prove that activity was recorded. Monitoring also does not imply tool blocking or AgentGuard behavioral threat scoring.

Onboarding, updates, and removal

New member: Team Setup runs when their computer starts. Repeat the coverage checks before marking them covered.
Helper update: revise the local helper, regenerate the manifest, and test it on a pilot group first. Then update the team manifest and verify a fresh Bot after application; an existing executor can retain old hooks.
Key rotation: create a replacement key and update the Team Secret’s value. After computers refresh or are recreated, confirm the new key’s Last used, then revoke the old key. Rotate between tool calls: in tool-only mode, changing keys changes the pre/post pairing boundary. Computers in more than one team keep the old key file; delete ~/.grokbot/runlayer_hook.key on them and use the single-user secret.
Member leaves: files already on their computer, including the saved key, stay there. Rotate the key if that computer may keep running.
Remove monitoring: disable Grok Bot in Runlayer and revoke its hook key. Delete the manifests and the Team Secret to stop reinstalling, then remove only Runlayer’s hook entries on each cloud computer. Removing the manifest alone does not undo installed files. Keep an allow-only helper at its existing path until cached executors no longer invoke it. Preserve unrelated hooks; the initial backup may predate other administrators’ later changes.

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Central Grok Bot setup

What is configured centrally

1. Prepare Runlayer

2. Save the key as a Team Secret

3. Build the setup script manifest

4. Pilot on a group

5. Publish to the team

6. Verify coverage for every member

Onboarding, updates, and removal

​What is configured centrally

​1. Prepare Runlayer

​2. Save the key as a Team Secret

​3. Build the setup script manifest

​4. Pilot on a group

​5. Publish to the team

​6. Verify coverage for every member

​Onboarding, updates, and removal

What is configured centrally

1. Prepare Runlayer

2. Save the key as a Team Secret

3. Build the setup script manifest

4. Pilot on a group

5. Publish to the team

6. Verify coverage for every member

Onboarding, updates, and removal