Skip to main content
Use this guide to prepare one centrally managed hook installation for your Grok Bot organization. An administrator distributes the helper and hook configuration; each member still provisions a credential on their cloud computer.
Grok Bot monitoring is experimental, disabled by default, and monitor-only. Runlayer has verified native hooks against a local stack. Production ingestion and Enterprise Team Setup distribution still need validation. Pilot this rollout before relying on organization-wide coverage. There is no validated Runlayer workflow for centrally pushing the hook credential to every member.

What is configured centrally

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 requires Enterprise and a team administrator. Without it, 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 and the pilot

  1. Identify the Grok teams and members in scope. Start by testing the generated installer on one pilot cloud computer before saving a team-wide manifest.
  2. In Settings → Organization API Keys, create keys with only Grok Bot Hooks access. We recommend a separate key per member’s computer so you can revoke one installation independently. These remain organization API keys; their names do not establish the actor’s identity in recorded activity.
  3. 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.
  4. 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.
Using a shared hook key is possible, but revoking it affects every computer using it. Keep an administrator-owned inventory of member, key name, installer revision, and verification date. Do not put key values in this inventory.

2. Build the Team Setup 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. The helper reads RUNLAYER_GROK_BOT_HOOK_KEY at runtime; never embed a key. Save the following as build_grok_manifest.py beside that file. It generates runlayer-grok-team-setup.json for the Team Setup editor and runlayer-grok-setup.sh for the pilot. 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. It can be rerun without duplicating those registrations. If you previously installed Runlayer under a different helper path, remove that old registration before using this one.
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 cloud installer requires Python 3 and runs as the member’s cloud-computer user. It does not install dependencies or download code. For the pilot, copy runlayer-grok-setup.sh to the pilot’s cloud computer and run bash runlayer-grok-setup.sh there. Complete steps 3 and 5 for that member before publishing the manifest to the team.

3. Provision credentials for each member

Give each member their assigned scoped key through your organization’s approved secret-sharing process. On their Grok cloud computer, have them use Secrets → Add secret or a secure secret-entry card to save it as RUNLAYER_GROK_BOT_HOOK_KEY. Follow Create a scoped key for the tested flow.
Team Setup distributes files and commands. Its manifest is plain text, not a secret store. Keep credentials out of the manifest, helper, ordinary Bot chat, and shell history. Runlayer does not provide automatic fleet credential enrollment for this integration. Each member must complete the secure entry step.
An administrator saving a key on their own computer does not provision it on another member’s computer. Missing credentials cause the helper to skip upload while allowing the Bot to continue. A successful installation therefore does not mean monitoring is active. Check delivery from the actual hook process. An ordinary Shell process may not receive a secret that is available to native hooks. Never print the key to debug it.

4. Publish the central installation

After the pilot records activity successfully:
  1. In the Cursor dashboard, open Grok Bot → Team Setup for the intended team.
  2. Create a manifest, switch the editor to JSON, and paste the generated runlayer-grok-team-setup.json.
  3. Save it. Repeat for other Grok teams in the rollout.
Team Setup runs at computer startup and refreshes roughly daily. This manifest omits the optional check script so changes to the embedded helper reapply on refresh. Installation is repeatable. Coordinate a computer reset or 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.

5. Verify coverage for every member

Use a fresh Bot after installing hooks; existing executors may cache their prior configuration. Have each member run a harmless, uniquely labeled command such as printf 'runlayer-grok-check-ROLL_OUT_LABEL\n' on their cloud computer. For each member, record these results in the rollout inventory: 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: confirm the central installation has applied, provision that member’s key, and repeat the coverage checks before marking them covered.
  • Helper update: revise the local helper, regenerate the manifest, test the installer on the pilot, then update the existing manifest. Verify a fresh Bot after application; an existing executor can retain old hooks.
  • Key rotation: provision the replacement through the secure entry flow, verify native activity, then revoke the old key. Rotate between tool calls: in tool-only mode, changing keys changes the pre/post pairing boundary.
  • Member leaves: revoke their dedicated hook key and remove their saved secret. A shared key requires rotation on the remaining computers too.
  • Remove monitoring: disable Grok Bot in Runlayer and revoke its hook keys. Remove the Team Setup manifest to stop reinstalling it, 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.