> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud agent hooks

> Set up monitor-only native activity collection for Cursor Cloud Agents and Grok Bot.

Forge collects native command callbacks on the hosted computer. This setup is separate from Forge for devices. Both collectors are monitor-only. A policy match can produce a recorded governance outcome, but these collectors do not block, rewrite or stop the hosted agent.

Grok Bot monitoring is experimental. Its hosted runtime may emit only tool callbacks. Without a native conversation ID, Forge pairs a tool call and its result using the native tool-use ID. It does not infer a conversation across different tool calls.

See the [native hook coverage matrix](https://docs.forge.ai/integrations/native-hook-coverage.md) for reviewed versions, emitted-event limits, tested artifacts and remaining gaps.

## Before you begin

You need organization administrator access in Forge, permission to update the provider's image or team setup, and permission to configure provider secrets. The hosted computer needs Python 3, an outbound HTTPS connection to your Forge API, a verified Linux Forge hook runtime, and private persistent storage.

In the provider setup dialog, select **Download Linux runtime** to obtain the selected `x86_64-unknown-linux-gnu` release artifact. For other architectures, ask your deployment administrator for a qualified artifact. Verify its target, version, SHA-256 and authenticated release manifest before installing it as `/opt/forge/bin/forge-hook`. Do not substitute a laptop executable or download an unpinned executable in each callback. If your release has no qualified Linux artifact for this image, complete credential/configuration setup and ask your deployment administrator for the artifact before enabling collection.

## Create the collector credential

1. Open **Settings > Cloud hooks** in Forge.
2. Under **Cloud agent hooks**, select **Set up Cursor Cloud Agents** or **Set up Grok Bot**.
3. For Cursor Cloud, enter a repository scope such as `owner/repository`. This scope comes from the credential, never from callback JSON.
4. Select **Create collector credential**. Copy the credential and save its key ID. Forge shows the secret only during this setup. Credentials expire after 30 days.
5. Download the native configuration and the cloud hook installer.

Create a separate Cursor Cloud key per repository and a separate Grok Bot key per member's hosted computer. The keys authorize only the selected collector's write endpoint. They do not authorize endpoint enrollment, data reads or organization administration.

## Set up Cursor Cloud Agents

1. Install the verified runtime in the provider image.
2. Add `FORGE_CLOUD_HOOK_TOKEN` to the provider's secure setup environment. Set it to the copied credential. Do not commit the token to the repository or print it in setup logs.
3. Place `install-cloud-hooks.py` and `forge-cursor_cloud-hooks.json` in the setup workspace.
4. Run the following command as the user whose agent executes the hooks, from the repository root.

```sh theme={"system"}
python3 install-cloud-hooks.py --family cursor_cloud \
  --config forge-cursor_cloud-hooks.json \
  --token-env FORGE_CLOUD_HOOK_TOKEN \
  --path .cursor/hooks.json
```

The installer writes the credential to `~/.forge/cloud-hooks/cursor_cloud.token` with owner-only permissions. Native hooks can read it even when setup secrets are absent from the hook process environment. The native configuration contains the collector URL and command, without the credential.

Keep `~/.forge/cloud-hooks/cursor_cloud/state` private, writable and persistent across restarts. The generated command uses this location by default. If your provider requires a persistent volume at another path, set `FORGE_HOOK_STATE_DIR` in the hook process environment. Do not share the directory between unrelated users or collector families.

Start a fresh cloud agent after changing the image or configuration. Hooks begin after the environment becomes writable, so initial prompts and earlier read-only activity may be absent. Dedicated MCP callbacks are unavailable in cloud agents. Generic tool callbacks can expose HTTP MCP tool names with redacted results; do not interpret a redacted result as inspected content.

## Set up Grok Bot

1. Install the verified runtime and installer in Enterprise Team Setup or your provider image.
2. Add `FORGE_GROK_BOT_HOOK_TOKEN` as a secure setup secret for the member computer. Do not embed it in a team manifest.
3. Distribute `forge-grok_bot-hooks.json` as non-secret configuration.
4. Run the following command as the hosted computer user during setup.

```sh theme={"system"}
python3 install-cloud-hooks.py --family grok_bot \
  --config forge-grok_bot-hooks.json \
  --token-env FORGE_GROK_BOT_HOOK_TOKEN
```

This installs owned entries in `~/.cursor/hooks.json` and writes the private credential to `~/.forge/cloud-hooks/grok_bot.token`. This is the hosted Bot configuration, separate from local Grok CLI configuration under `~/.grok`. Keep `~/.forge/cloud-hooks/grok_bot/state` private and persistent. Team setup secrets can be unavailable directly to hook commands; the private file bridges that boundary.

Create a fresh Bot for each pilot member after setup. Registered callbacks do not prove that the runtime emits them. The independently documented Grok pilot covers `preToolUse`, `postToolUse` and `postToolUseFailure`. Other registered callbacks require your own provider validation. Do not use a shared computer ID as a replacement for a missing Bot or conversation ID.

## Verify delivery in Forge

1. From a fresh hosted agent, run a harmless tool action with a distinctive value, such as `printf 'forge-hook-pilot-<your-value>\n'`.
2. Open **Live > Sessions** in Forge and select the corresponding product. Check the timestamp, repository or member scope, native tool name, call and result. When the provider emits a conversation ID, check that the messages share that conversation. A Grok activity without that ID remains tool-scoped.
3. If the provider emits prompt and response callbacks with a generation ID, check their links to the observed prompt. Missing callbacks remain coverage gaps.
4. Open the message's governance details. A completed evaluation and its linked outcome prove governance processing. An intervention request alone does not prove an action ran. A violation appears only when the policy/evaluation writer produces an applicable violation.
5. Restart the executor without deleting its state directory, then run another tool call. Check delivery again. During an approved pilot outage, retain the same credential and state directory, restore connectivity, drain retained events, and verify that replay does not duplicate messages or outcomes.

The download requires a release manifest that declares private collector credential support. An older runtime without that capability is unavailable in this setup. Publication and verification of a compatible release precede provider rollout.

Creating a credential, downloading configuration or accepting an HTTP callback does not confirm that a provider emitted callbacks or that persistence completed. Do not mark a team rollout verified until each pilot member passes the fresh-executor check.

If Forge reports that existing cloud identity data requires migration, stop setup and contact your administrator. Existing source records must be reconciled before this scoped collector version projects more data. Do not delete retained events or create replacement credentials to bypass this check.

## Retry and recovery

Native callbacks always allow the provider action to proceed. Collection failures retain eligible events in the shared bounded spool. Successful queue admission precedes asynchronous evidence and governance persistence. Keep the private state directory through restarts and recover connectivity within its configured retention window.

To explicitly retry retained callbacks, run the same verified executable as the hook user, with the same token file, collector URL and state directory.

```sh theme={"system"}
FORGE_CONTROL_PLANE_URL=https://your-forge-api.example \
FORGE_HOOK_STATE_DIR="$HOME/.forge/cloud-hooks/grok_bot/state" \
/opt/forge/bin/forge-hook --cloud-collector --drain \
  --source-adapter-key grok_bot
```

For Cursor Cloud, substitute `cursor_cloud` and its state directory. The runtime binds retained callbacks to the credential fingerprint. A replacement credential cannot relabel old retained events. If a key expires or is revoked before its backlog drains, preserve the state and contact your administrator; do not edit the spool or fabricate a new source identity.

## Rotate or revoke a credential

Before expiry, drain retained events using the old key. For Grok, rotate between tool calls because the credential scopes tool-only identity. Create a replacement in Forge, update the provider setup secret, and rerun the installer with `--token-env`. Start a fresh agent and verify delivery before revoking the old key.

To revoke, open the provider setup in **Settings > Cloud hooks**, enter the saved `chk_...` key ID and select **Revoke credential**. Revocation stops new admission immediately. Already admitted encrypted queue items can finish persistence. Remove revoked secrets from the provider secret store and hosted computer.

## Uninstall

For Grok Bot, run the following command as the hosted computer user.

```sh theme={"system"}
python3 install-cloud-hooks.py --family grok_bot --uninstall --remove-token
```

For Cursor Cloud, run the command from the repository root.

```sh theme={"system"}
python3 install-cloud-hooks.py --family cursor_cloud \
  --path .cursor/hooks.json --uninstall --remove-token
```

Revoke the credential in Forge and remove the provider setup secret. The installer removes only the selected family's owned entries and private credential. It preserves unrelated native hooks, the first configuration backup and delivery state. Drain retained state before uninstall when possible. Delete the retained state only after your retention and recovery requirements permit it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.