Cloudflare Worker

This guide deploys Inception Agents as a Cloudflare Worker that sits in front of your origin server. All traffic flows through the Worker. Human visitors are proxied to your origin unmodified. AI agents receive optimized content served directly from the edge with sub-5ms detection latency.

What to Expect

After deployment, the Worker begins intercepting and classifying traffic immediately. Agent detection is active from the first request. Content optimization and llms.txt generation run automatically. Dashboard data populates as agent traffic arrives, typically within 24-48 hours.

One-Click Setup with Claude Code

If you use Claude Code, you can deploy the entire integration in one step. Copy the prompt below, paste it into Claude Code, and it will scaffold the project, install dependencies, create the KV namespace, set your API key, deploy the Worker, and verify everything is working.

Before you start: Have your Inception Agents API key ready (find it in Settings > API Keys in the dashboard).

I need you to deploy an Inception Agents Cloudflare Worker for my website. Follow these steps exactly:

1. Create a new directory called "inception-worker" and initialize it:
   mkdir inception-worker && cd inception-worker
   npm init -y
   npm install @inception-agents/cloudflare
   npm install -D wrangler typescript @cloudflare/workers-types

2. Create src/index.ts with this exact content:
   import { createInceptionHandler } from '@inception-agents/cloudflare';
   export interface Env {
     INCEPTION_API_KEY: string;
     INCEPTION_CACHE: KVNamespace;
   }
   export default {
     async fetch(request: Request, env: Env): Promise<Response> {
       const handler = createInceptionHandler({
         apiKey: env.INCEPTION_API_KEY,
         originUrl: 'ORIGIN_URL',
         kvCache: env.INCEPTION_CACHE,
         kvCacheTtl: 3600,
       });
       return handler(request);
     },
   };

3. Create tsconfig.json:
   { "compilerOptions": { "target": "ES2021", "module": "ES2022", "moduleResolution": "bundler", "types": ["@cloudflare/workers-types"] } }

4. Create the KV namespace:
   npx wrangler kv namespace create INCEPTION_CACHE
   Save the namespace ID from the output.

5. Create wrangler.toml using the KV namespace ID from step 4:
   name = "inception-agents-proxy"
   main = "src/index.ts"
   compatibility_date = "2024-01-01"
   [[kv_namespaces]]
   binding = "INCEPTION_CACHE"
   id = "<KV_NAMESPACE_ID>"

6. Set the API key secret:
   npx wrangler secret put INCEPTION_API_KEY
   When prompted, enter: <YOUR_API_KEY>

7. Deploy:
   npx wrangler deploy

8. Verify with these curl commands (replace YOUR_DOMAIN):
   curl -s https://YOUR_DOMAIN/llms.txt
   curl -s -D - -H "User-Agent: GPTBot/1.0" https://YOUR_DOMAIN/ | head -20

IMPORTANT: Ask me for these values before starting:
- My origin URL (the site I want to protect/optimize)
- My Inception Agents API key
- My domain name for verification

Replace ORIGIN_URL with your origin server URL, YOUR_API_KEY with your API key, and YOUR_DOMAIN with your domain. Claude Code will walk through each step, handle errors, and verify the deployment.

Prefer to do it manually? Follow the step-by-step guide below.

Prerequisites

• A Cloudflare account with Workers enabled (free tier is sufficient for getting started)
• Node.js 18 or later
• Wrangler CLI installed (npm install -g wrangler)
• An Inception Agents API key (sign up, then find it in Settings > API Keys)

Step 1: Install the Package

npm install @inception-agents/cloudflare

Step 2: Create the Worker

Create your Worker entry point:

// src/index.ts
import { createInceptionHandler } from '@inception-agents/cloudflare';

export interface Env {
  INCEPTION_API_KEY: string;
  INCEPTION_CACHE: KVNamespace;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const handler = createInceptionHandler({
      apiKey: env.INCEPTION_API_KEY,
      originUrl: 'https://your-site.com',
      kvCache: env.INCEPTION_CACHE,
      kvCacheTtl: 3600,
    });

    return handler(request);
  },
};

Replace https://your-site.com with your origin server URL.

Step 3: Configure wrangler.toml

name = "inception-agents-proxy"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[[kv_namespaces]]
binding = "INCEPTION_CACHE"
id = "your-kv-namespace-id"

Create the KV Namespace

npx wrangler kv namespace create INCEPTION_CACHE

Copy the id from the output into your wrangler.toml. If you also want a preview namespace for local development:

npx wrangler kv namespace create INCEPTION_CACHE --preview

Add the preview ID to your wrangler.toml:

[[kv_namespaces]]
binding = "INCEPTION_CACHE"
id = "your-kv-namespace-id"
preview_id = "your-preview-kv-namespace-id"

Step 4: Set Your API Key

npx wrangler secret put INCEPTION_API_KEY

Enter your API key when prompted. This stores the key securely as an encrypted secret — it will not appear in your wrangler.toml or source code.

Step 5: Deploy

npx wrangler deploy

The Worker is now live. Configure your domain’s DNS to route traffic through the Worker using a Workers Route or Custom Domain.

Step 6: Verify

Check llms.txt

curl -s https://your-domain.com/llms.txt

Expected: a markdown document describing your site.

Check Agent Detection

curl -s -D - \
  -H "User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.0" \
  https://your-domain.com/ | head -20

Expected: response headers include X-Inception-Agent: detected and X-Inception-Agent-Platform: openai.

Check Human Passthrough

curl -s -D - \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/120.0.0.0 Safari/537.36" \
  https://your-domain.com/ | head -20

Expected: your normal origin response, unmodified. No X-Inception-Agent header.

Detection-Only Mode

If you want to detect and log agent traffic without serving optimized content, use detection-only mode. This is useful for auditing agent traffic before enabling full optimization.

// src/index.ts
import { createInceptionHandler } from '@inception-agents/cloudflare';

export interface Env {
  INCEPTION_API_KEY: string;
  INCEPTION_CACHE: KVNamespace;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const handler = createInceptionHandler({
      apiKey: env.INCEPTION_API_KEY,
      originUrl: 'https://your-site.com',
      kvCache: env.INCEPTION_CACHE,
      kvCacheTtl: 3600,
      mode: 'detect-only',
    });

    return handler(request, ctx);
  },
};

In this mode, the Worker detects agents and logs events to the dashboard but proxies all traffic (human and agent) to the origin without modification.

Configuration Options

Pass these options to createInceptionHandler:

Request Routing

The Worker routes requests based on detection results:

Troubleshooting

llms.txt Returns 404

• Confirm enableLlmsTxt is not set to false in your handler config.
• Check that the KV namespace is correctly bound. Run npx wrangler kv key list --namespace-id YOUR_NAMESPACE_ID to verify the namespace exists and is accessible.
• Ensure the Worker has been deployed after KV was configured: npx wrangler deploy.

KV Cache Not Working

• Verify the KV namespace ID in wrangler.toml matches the one created by npx wrangler kv namespace create.
• Check that the kvCache parameter is passed to createInceptionHandler and references the correct env binding.
• View KV contents: npx wrangler kv key list --namespace-id YOUR_NAMESPACE_ID.

No Agent Traffic in Dashboard

• Agent traffic depends on AI platforms crawling your domain. Verify detection is working with the curl commands in Step 6.
• Enable debug: true and check Worker logs: npx wrangler tail.
• Confirm your INCEPTION_API_KEY secret is set: npx wrangler secret list.

Origin Errors (502, 504)

• Verify originUrl is correct and your origin is accessible from Cloudflare’s network.
• Check that your origin does not block requests from Cloudflare IP ranges.
• Review Worker logs for connection errors: npx wrangler tail.

High Latency

• Ensure KV caching is enabled. Without KV, every agent request hits the origin.
• Increase kvCacheTtl if content does not change frequently.
• Add high-traffic paths that do not need agent detection to excludePaths.

Uninstall

Step 1: Remove the Worker

npx wrangler delete

Or delete the Worker from the Cloudflare dashboard under Workers & Pages.

Step 2: Update DNS

If you configured a Workers Route or Custom Domain, remove it and point DNS back to your origin.

Step 3: Clean Up KV

Delete the KV namespace if you no longer need it:

npx wrangler kv namespace delete --namespace-id YOUR_NAMESPACE_ID

Step 4: Remove the Package

npm uninstall @inception-agents/cloudflare

Remove the INCEPTION_API_KEY secret:

npx wrangler secret delete INCEPTION_API_KEY