Grok Bot

Grok Bot runs work on a cloud computer. The macOS desktop app and iOS app are control surfaces, so they do not inherit AI Watch binaries, MDM settings, or the local Grok CLI hooks under ~/.grok. Use Grok Bot’s Cursor-format team or plugin hooks to send session events to Runlayer. This integration is monitor-only: the collector cannot block tools, enforce MCP policy, read Runlayer data, or administer your workspace.

1. Create a scoped key

In Runlayer, go to Settings → Organization API Keys, create a key with only the Grok Bot Hooks permission, and copy it when shown. Runlayer stores only its hash. Add the value to the Grok Bot team or cloud-computer secret store as RUNLAYER_GROK_BOT_HOOK_KEY. Do not commit it to a repository, and do not use an AI Watch organization key or Agent Account secret.

2. Add the hook helper

Create .grokbot/runlayer_hook.py in each repository used by Grok Bot. Replace the hostname in COLLECTOR_URL with your Runlayer tenant hostname. Keep the full HTTPS URL literal so repository content cannot redirect the credential.

#!/usr/bin/env python3
import os
import sys
import time
import urllib.error
import urllib.request
import uuid

COLLECTOR_URL = "https://YOUR-TENANT.runlayer.com/api/v1/hooks/grok-bot/events"
MAX_PAYLOAD_BYTES = 256 * 1024
ALLOW = '{"permission":"allow"}'


class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None


def deliver(payload: bytes, key: str) -> None:
    delivery_id = str(uuid.uuid4())
    request = urllib.request.Request(
        COLLECTOR_URL,
        data=payload,
        method="POST",
        headers={
            "Content-Type": "application/json",
            "X-Runlayer-Delivery-ID": delivery_id,
            "x-runlayer-api-key": key,
        },
    )
    opener = urllib.request.build_opener(NoRedirect)
    for attempt, delay in enumerate((0, 0.2, 0.8)):
        if delay:
            time.sleep(delay)
        try:
            with opener.open(request, timeout=2) as response:
                if 200 <= response.status < 300:
                    return
        except urllib.error.HTTPError as error:
            if error.code < 500 and error.code != 429:
                return
            if attempt == 2:
                return
        except (urllib.error.URLError, TimeoutError):
            if attempt == 2:
                return


def main() -> int:
    try:
        payload = sys.stdin.buffer.read(MAX_PAYLOAD_BYTES + 1)
        key = os.environ.get("RUNLAYER_GROK_BOT_HOOK_KEY", "")
        if key and len(payload) <= MAX_PAYLOAD_BYTES:
            deliver(payload, key)
    except Exception:
        pass
    sys.stdout.write(ALLOW)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

The helper reuses one delivery ID across transient retries, never logs the key or payload, and always returns Grok Bot’s explicit allow response. A Runlayer outage therefore cannot block or change a Bot run.

3. Register supported team hooks

In Grok Bot, add command hooks for the events below at team scope. Teams that manage Cursor-format plugins as code can use this as hooks/hooks.json in the plugin and assign the plugin to Grok Bot users. Runlayer supports exactly the configured events below. This list defines the integration contract; it is not a claim that every Grok Bot version emits every event during every run. Other event names are rejected by the collector.

{
  "version": 1,
  "hooks": {
    "sessionStart": [{ "command": "python3 .grokbot/runlayer_hook.py", "timeout": 3, "failClosed": false }],
    "sessionEnd": [{ "command": "python3 .grokbot/runlayer_hook.py", "timeout": 3, "failClosed": false }],
    "beforeSubmitPrompt": [{ "command": "python3 .grokbot/runlayer_hook.py", "timeout": 3, "failClosed": false }],
    "afterAgentThought": [{ "command": "python3 .grokbot/runlayer_hook.py", "timeout": 3, "failClosed": false }],
    "preToolUse": [{ "command": "python3 .grokbot/runlayer_hook.py", "timeout": 3, "failClosed": false }],
    "postToolUse": [{ "command": "python3 .grokbot/runlayer_hook.py", "timeout": 3, "failClosed": false }],
    "postToolUseFailure": [{ "command": "python3 .grokbot/runlayer_hook.py", "timeout": 3, "failClosed": false }],
    "subagentStart": [{ "command": "python3 .grokbot/runlayer_hook.py", "timeout": 3, "failClosed": false }],
    "subagentStop": [{ "command": "python3 .grokbot/runlayer_hook.py", "timeout": 3, "failClosed": false }],
    "afterAgentResponse": [{ "command": "python3 .grokbot/runlayer_hook.py", "timeout": 3, "failClosed": false }],
    "stop": [{ "command": "python3 .grokbot/runlayer_hook.py", "timeout": 3, "failClosed": false }],
    "preCompact": [{ "command": "python3 .grokbot/runlayer_hook.py", "timeout": 3, "failClosed": false }]
  }
}

Start a new Bot run, then open Sessions in Runlayer and filter for Grok Bot. If events do not appear, confirm Grok Bot is enabled under Settings → Agent session monitoring, the secret is available on the cloud computer, and the collector URL uses the correct tenant hostname.

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

1. Create a scoped key

2. Add the hook helper

3. Register supported team hooks

​1. Create a scoped key

​2. Add the hook helper

​3. Register supported team hooks

1. Create a scoped key

2. Add the hook helper

3. Register supported team hooks