Install Formal Endpoint on Grok Bot

Overview

Grok Bot computers are Linux VMs with a browser and a terminal. Install the Formal Endpoint on every team computer with Enterprise Team Setup. Transparent Mode then evaluates the VM traffic against Formal policy. This guide blocks https://mail.google.com and https://gmail.com. Gmail serves the inbox on both hostnames. A rule that matches only one is bypassed.

Prerequisites

A Cursor Enterprise team with Grok Bot Team Setup
Outbound HTTPS to api.joinformal.com

Create an API key

Use one machine-user API key for the Grok Bot fleet.

Create the key

Go to API Keys and click Create API Key. Assign it to a machine user.

Store it as a Team Secret

Open Grok Bot in the Cursor dashboard. Add a Team Secret named FORMAL_API_KEY. Paste the Formal key. Team Setup injects Team Secrets as environment variables. Do not put the key in the setup script.

Install the Endpoint with Team Setup

Create a manifest

Go to Grok Bot → Team Setup. Create a manifest, for example formal-endpoint. Add one entry with ID install-formal-endpoint.

Copy the package link

In the Control Plane, click Download Formal Endpoint at the bottom of the sidebar. Open Linux, right-click Ubuntu/Debian (x86, headless), and copy the link.

Paste the setup script

#!/usr/bin/env bash
set -euo pipefail

: "${FORMAL_API_KEY:?Set the FORMAL_API_KEY Team Secret}"

curl --fail --silent --show-error --location \
  "<FORMAL_ENDPOINT_PACKAGE_URL>" \
  --output /tmp/formal-desktop-headless.deb
# Skip apt-get update — it can hang here; the local .deb is enough.
sudo apt-get install --yes /tmp/formal-desktop-headless.deb

mkdir -p ~/.formal/logs
printf 'FORMAL_API_KEY=%s\n' "$FORMAL_API_KEY" > ~/.formal/formal.env
chmod 0600 ~/.formal/formal.env
cat > ~/.formal/config.toml <<'EOF'
[transparent_proxy]
enable = true
EOF

sudo mkdir -p /var/lib/formal/ca
sudo chgrp "$(id -gn)" /var/lib/formal/ca
sudo chmod 0775 /var/lib/formal/ca
sudo usermod -aG sudo "$(id -un)" || true
sudo setcap 'cap_net_admin,cap_net_bind_service+ep' /usr/bin/formal || true

set -a
# shellcheck disable=SC1091
source "$HOME/.formal/formal.env"
set +a

# Do not use pkill -f '/usr/bin/formal agent' — under bash -c the setup
# cmdline embeds that string and the script will kill itself.
pkill -f '^/usr/bin/formal agent --headless$' 2>/dev/null || true
# Wait for the old agent to drop its instance lock before starting another.
for _ in $(seq 1 20); do
  pgrep -f '^/usr/bin/formal agent --headless$' >/dev/null 2>&1 || break
  sleep 0.25
done

# New session so the agent is not killed with the setup process group.
setsid nohup /usr/bin/formal agent --headless \
  >> ~/.formal/logs/agent.log 2>&1 < /dev/null &

ca_pem=/var/lib/formal/ca/localca-cert.pem
for _ in $(seq 1 60); do
  if [[ -f "$ca_pem" ]] && formal auth status >/dev/null 2>&1; then
    break
  fi
  sleep 1
done
[[ -f "$ca_pem" ]] || { echo "Formal CA not ready; see ~/.formal/logs/agent.log" >&2; exit 1; }
formal auth whoami >/dev/null || { echo "Formal auth failed; see ~/.formal/logs/agent.log" >&2; exit 1; }

sudo formal ca trust

ca_crt=/usr/local/share/ca-certificates/formal-localca.crt
sudo mkdir -p /etc/opt/chrome/policies/managed
# Cert is root-only after `formal ca trust`; openssl must run as root.
der_b64="$(sudo openssl x509 -in "$ca_crt" -outform DER | base64 -w0)"
printf '{"CACertificates":["%s"]}\n' "$der_b64" \
  | sudo tee /etc/opt/chrome/policies/managed/formal-localca.json >/dev/null
sudo chmod 644 /etc/opt/chrome/policies/managed/formal-localca.json

formal auth status
formal auth whoami
formal transparent-proxy status || true

The Chrome policy trusts the Formal CA. Without it, Chrome shows a certificate warning instead of the Formal block page.Replace <FORMAL_ENDPOINT_PACKAGE_URL> with the copied link. To upgrade the Endpoint, copy the link again and update the script.

Add the check script

#!/usr/bin/env bash
set -euo pipefail
formal auth whoami >/dev/null

ca_pem=/var/lib/formal/ca/localca-cert.pem
[[ -f "$ca_pem" ]]
sudo mkdir -p /etc/opt/chrome/policies/managed
der_b64="$(openssl x509 -in "$ca_pem" -outform DER | base64 -w0)"
printf '{"CACertificates":["%s"]}\n' "$der_b64" \
  | sudo tee /etc/opt/chrome/policies/managed/formal-localca.json >/dev/null
sudo chmod 644 /etc/opt/chrome/policies/managed/formal-localca.json

A zero exit skips setup. After setup runs, Team Setup runs this check again. The check also rewrites Chrome’s Formal CA policy. Headless Linux issues a new CA when the agent starts. formal auth whoami succeeding means that new CA is already on disk. If the agent is not running after a reboot, the check fails and setup starts it again.

Save and apply

Save the manifest. New computers apply it on start. To apply it now, open Grok Bot → Settings → Updates → Reset, or recreate the computer from the dashboard.

Verify:

formal auth whoami
formal transparent-proxy status

formal auth whoami should show the machine user that owns the API key. Transparent Mode should be enabled.

Create the network rule

The Endpoint forwards a connection unless a network rule matches. This rule terminates TLS for Gmail so policy can run.

Control Plane
Terraform

Navigate to Network Rules
Create a rule named gmail-grok-bot
Paste the CEL below
Leave Forward to Connector unset
Save the rule and set it to Active

{
  "condition": {
    "pre_tls": hostname in ["gmail.com", "www.gmail.com", "mail.google.com"],
    "post_tls": true
  }
}

resource "formal_network_rule" "gmail_grok_bot" {
  name        = "gmail-grok-bot"
  description = "Intercept Gmail traffic from Grok Bot computers"
  status      = "active"

  cel_expression = <<-EOT
    {
      "condition": {
        "pre_tls": hostname in ["gmail.com", "www.gmail.com", "mail.google.com"],
        "post_tls": true
      },
      "outputs": {}
    }
  EOT
}

To limit the rule to the Grok Bot machine user, add && user.id == "<MACHINE_USER_ID>" to pre_tls.

Create the Gmail policy

Block every HTTP request to those hostnames. Create the policy in and set it to Active.

Control Plane
Terraform

Navigate to Policies
Click Create Policy
Name it block-grok-bot-gmail
Paste the Rego below
Save and set the policy to Active

package formal.v2

import future.keywords.if
import future.keywords.in

request := {
  "action": "block",
  "type": "block_with_formal_message",
  "reason": "Grok Bot cannot open Gmail",
} if {
  input.http.hostname in {"gmail.com", "www.gmail.com", "mail.google.com"}
}

resource "formal_policy" "block_grok_bot_gmail" {
  name        = "block-grok-bot-gmail"
  description = "Block Grok Bot from opening Gmail"
  status      = "active"

  module = <<-EOT
    package formal.v2

    import future.keywords.if
    import future.keywords.in

    request := {
      "action": "block",
      "type": "block_with_formal_message",
      "reason": "Grok Bot cannot open Gmail",
    } if {
      input.http.hostname in {"gmail.com", "www.gmail.com", "mail.google.com"}
    }
  EOT
}

Verify Gmail is blocked

Ask a Bot to open https://mail.google.com in the computer browser. Chrome should show Formal’s block page with a policy ID, session ID, and request ID. Also try https://gmail.com. Both hosts should block. Open Logs. Filter to Endpoint. Confirm the blocked request hostname is mail.google.com or gmail.com.

Troubleshooting

Team Setup did not install Formal

Confirm the team is on Enterprise and the manifest is saved. Reset the computer from Grok Bot → Settings → Updates → Reset. Confirm the Team Secret is named FORMAL_API_KEY. A computer that belongs to more than one team does not receive Team Secrets.

formal auth whoami fails

Confirm the agent is running and read its log:

pgrep -x formal || true
tail -n 50 ~/.formal/logs/agent.log

Confirm the API key is valid. Reset the computer so Team Setup starts the agent again.

Chrome shows a certificate warning

Confirm /etc/opt/chrome/policies/managed/formal-localca.json exists. The check script rewrites it from the live Formal CA after the agent starts. Reset the computer if Team Setup has not run since boot. Restart Chrome after that. Do not disable TLS verification.

The policy does not evaluate

Confirm the policy and the Gmail network rule are Active. Confirm Transparent Mode is enabled. Without a matching rule, the Endpoint forwards Gmail without inspecting it. Confirm Grok Bot’s own network policy allows mail.google.com.

Next steps

Linux Endpoint

Review the headless package and systemd service

Network Rules

Select which traffic Transparent Mode intercepts

Policy Evaluation

Explore HTTP policy inputs

Endpoint Logs

Review requests and policy decisions

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

Install Formal Endpoint on Grok Bot

Overview

Prerequisites

Create an API key

Install the Endpoint with Team Setup

Create the network rule

Create the Gmail policy

Verify Gmail is blocked

Troubleshooting

Next steps

Linux Endpoint

Network Rules

Policy Evaluation

Endpoint Logs

​Overview

​Prerequisites

​Create an API key

​Install the Endpoint with Team Setup

​Create the network rule

​Create the Gmail policy

​Verify Gmail is blocked

​Troubleshooting

​Next steps

Linux Endpoint

Network Rules

Policy Evaluation

Endpoint Logs

Overview

Prerequisites

Create an API key

Install the Endpoint with Team Setup

Create the network rule

Create the Gmail policy

Verify Gmail is blocked

Troubleshooting

Next steps