ForceFlake AI - Installation & Setup Guide

AI

for Salesforce

Installation & Setup Guide

Step-by-Step Configuration for Administrators

ForceFlake Mascot
Version 1.0  |  February 2026  |  raj@forceflake.com

Prerequisites

Before installing ForceFlake AI, ensure the following requirements are met:

  • Salesforce org (Developer, Sandbox, or Production)
  • System Administrator profile or equivalent permissions
  • Internet access from your Salesforce org (no firewall blocking Heroku)

Overview

ForceFlake AI is an AI-powered metadata documentation and chatbot for Salesforce. It connects your Salesforce org to AI providers (Anthropic Claude, OpenAI, Google Gemini) through a secure Heroku gateway. This guide walks you through the complete setup process from installation to your first AI-powered chat.

Architecture

LayerComponentDescription
FrontendSalesforce Managed PackageLWC chat UI, Apex controllers, metadata services
MiddlewareHeroku AI GatewayJWT auth, rate limiting, usage tracking, provider routing
BackendAI ProvidersAnthropic Claude, OpenAI GPT, Google Gemini
1
Phase 1: Install the Package

Install ForceFlake AI from the Salesforce AppExchange or via a package installation URL provided by your administrator.

  1. Log in to your Salesforce org as a System Administrator.
  2. Navigate to the ForceFlake AI AppExchange listing, or use the installation URL provided.
  3. Click Install for All Users (recommended) or select specific profiles.
  4. Review and approve third-party access for the Heroku gateway endpoint.
  5. Wait for the installation to complete. You will receive a confirmation email.
Automatic Setup

On installation, ForceFlake AI automatically deploys a default AI configuration (Anthropic Claude, 4096 max tokens) and attempts to register your org with the Heroku AI Gateway via a background job. If auto-registration succeeds, you may skip Step 1 in Phase 2.

2
Phase 2: Configure AI Settings

After installation, navigate to the AI Settings page to verify and complete the configuration. From the Salesforce App Launcher, search for and open the ForceFlake AI app, then click the AI Settings tab in the navigation bar.

Step 1: Register with the AI Gateway

This step connects your Salesforce org to the ForceFlake Heroku AI Gateway. Registration generates a secure JWT authentication token that is stored in a protected custom setting and used for all subsequent AI requests.

  1. In the AI Settings page, click the AI Gateway tab.
  2. Under Step 1: Register with ForceFlake AI Gateway, click the Register Org button.
  3. Wait for the registration to complete. You should see a success toast: "Org registered successfully. Auth token saved."
  4. The Setup Status bar at the top should now show Gateway Connected with a green checkmark.
Already Registered?

If the post-install handler successfully registered your org automatically, you will already see "Gateway Connected" in the Setup Status bar. You can skip this step. To re-register (e.g., after rotating credentials), click Re-register Org.

Registration Failed?

Verify that: (1) Your Heroku gateway is running (check the /health endpoint). (2) The Remote Site Setting FF_Heroku_Gateway is active and points to your correct Heroku URL. (3) Your org has internet access to the Heroku domain.

Step 2: Choose AI Provider and Model

Select your preferred AI provider and model. The default configuration uses Anthropic Claude, which is recommended for Salesforce metadata tasks.

  1. In the AI Gateway tab, locate Step 2: Choose AI Provider.
  2. Select your AI Provider from the dropdown: Anthropic (Claude), OpenAI (GPT), or Google Gemini.
  3. Select your preferred AI Model. The recommended default is claude-sonnet-4-5-20250929.
  4. Set the Max Tokens value (default: 4096, max: 32768).

Available Providers

ProviderModelsBest For
Anthropic (Claude) Recommended claude-sonnet-4-5, claude-haiku-4-5, claude-opus-4-5 Excellent at Salesforce metadata analysis, documentation, and code review.
OpenAI (GPT) gpt-4o, gpt-4o-mini, gpt-4-turbo, o1, o3-mini Strong general-purpose AI with good code understanding.
Google Gemini gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash Fast responses with competitive quality. Good for high-volume usage.

Step 3: Bring Your Own Key (Optional)

By default, ForceFlake AI routes requests through its managed API keys, subject to your subscription plan's monthly token limits. Provide your own key for unlimited usage.

  1. Locate Step 3: Bring Your Own Key (Optional).
  2. Enter your API key in the Your API Key (BYOK) field. Anthropic: sk-ant-api03-..., OpenAI: sk-..., Gemini: AIza...
  3. Click Save API Key. You should see: "API key saved securely."
  4. A green checkmark confirms your BYOK key is active. All requests now use your key.
BYOK Security

Your API key is stored in a Protected Custom Setting (FF_AI_Secure_Settings__c), encrypted at rest and accessible only by the managed package code. It is never exposed to users, admin pages, or SOQL queries outside the package.

Step 4: Custom System Prompt (Optional)

Customize the system prompt that guides the AI's behavior. The default is optimized for Salesforce metadata tasks. Only change this if you have specific requirements.

  1. Scroll down to the Custom System Prompt text area.
  2. Enter your custom prompt, or leave blank to use the built-in default.

Step 5: Save Settings

After configuring your preferences, save all settings.

  1. Click the Save Settings button in the top-right corner of the AI Settings page.
  2. A success toast confirms: "AI configuration has been updated."
  3. The AI Configuration status in the Setup Status bar should now show a green checkmark.
3
Phase 3: Assign Permissions

ForceFlake AI includes two permission sets to control access. Assign the appropriate permission set to each user based on their role.

Permission SetAccess LevelIntended For
FF_AI_User Chat with AI, view metadata snapshots, read documentation, access all LWC components. Developers, business analysts who need to query org metadata.
FF_AI_Admin Full CRUD on all objects, configure AI settings, schedule scans, run batch processors. System administrators responsible for setup and maintenance.

How to Assign Permission Sets

  1. Go to Setup > Users > Permission Sets.
  2. Click on FF_AI_User or FF_AI_Admin.
  3. Click Manage Assignments > Add Assignment.
  4. Select the users and click Assign.
4
Phase 4: Configure Metadata Scheduler (Optional)

ForceFlake AI can automatically scan your org's metadata on a schedule. This keeps the AI's knowledge of your org up to date for more accurate answers.

  1. In the AI Settings page, click the Scheduler tab.
  2. Select a Scan Frequency: Daily, Weekly (Sunday), Bi-Weekly, or Monthly.
  3. Set the Scan Hour (0-23, 24-hour format). Recommended: off-peak hours like 2 AM.
  4. Click Schedule Scan. A toast message will display the cron expression.
  5. To run an immediate scan, click Run Scan Now.
Scheduling Tip

For most orgs, a weekly scan is sufficient. Daily scans are recommended for orgs with frequent metadata changes. The scan runs as a batch job and does not impact org performance.

5
Phase 5: Test Your Setup
ForceFlake Mascot

You're almost there!

Verify everything is working by sending your first AI chat message. The ForceFlake mascot is cheering you on!

  1. From the ForceFlake AI app, click the AI Chat tab in the navigation bar.
  2. Click New Chat to start a fresh conversation.
  3. Type a test message such as: "Give me a comprehensive overview of my Salesforce org including object counts, custom objects, and general configuration."
  4. Click Send and wait for the AI response (10-30 seconds).
  5. If you receive a response, your setup is complete. Congratulations!

Quick Actions Available

Quick ActionWhat It Does
Org OverviewGenerates a comprehensive summary of your org including object counts and configuration.
Document ObjectCreates detailed documentation for a selected object, including fields, relationships, and validation rules.
List FlowsLists all active Flows in the org with descriptions and types.
List ApexLists all Apex classes with their API versions, sizes, and descriptions.

Troubleshooting

IssueCauseSolution
"Missing or invalid Authorization header" Org not registered with gateway. No JWT token. AI Settings > AI Gateway > Click Register Org.
"Gateway callout failed" Heroku gateway is down or Remote Site URL is wrong. Verify /health endpoint. Check Remote Site Settings.
"Rate limit exceeded" Too many requests for your subscription tier. Wait and retry, or upgrade your plan.
"Monthly token limit reached" Monthly token budget exhausted. Wait for next cycle, upgrade, or use BYOK key.
Registration network error Firewall blocking Heroku requests. Whitelist *.herokuapp.com. Check Remote Site is active.

Support

ForceFlake Mascot

We're here to help!

For questions, issues, or feature requests:

  • ✉ Email: raj@forceflake.com
  • 📦 AppExchange: Submit a review or question on the listing page.
  • ❤ Health Check: Visit your gateway URL /health endpoint.

Thank you for choosing ForceFlake AI!

ForceFlake AI  |  Version 1.0  |  February 2026
forceflake.com  |  raj@forceflake.com

Click on me to get the appExchange App