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.

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