How to use kerf.box

Three ways to run it

1. No key — demo mode. Open the app and click run with demo data. You get a full, real kerf (canned) so you can see exactly what the output looks like before bringing a key. Copy generation works in demo mode too.
2. Your own AI key (BYOK). Pick a provider in the app — Anthropic, OpenAI, Gemini, Kimi, Qwen, DeepSeek, Groq, OpenRouter, a local Ollama, or any custom OpenAI-compatible endpoint — paste your key, and cut live kerfs. You pay your provider directly for tokens; kerf.box charges nothing and never sees your key beyond the single request it rides on.
3. From your agent (MCP or HTTP). Add npx -y kerfbox-mcp to Claude Desktop, Cursor, or any MCP client — or call the open HTTP API directly. Details below.

Cut your first kerf (90 seconds)

1. Open kerfbox.vercel.app/app.
2. Drop the product URL you want positioned.
3. Describe the audience in one line — the tighter the audience, the sharper the cut.
4. Pick your AI provider, paste your key (saved in your browser only), and hit Cut a kerf.
5. Watch the run stream in: cluster map → kerf → wedge → 7-day calendar. Click any calendar entry to generate platform-ready copy.
6. Save it to your browser archive, or export as JSON / markdown for Notion, Linear, or Slack.

If the run is refused, that is the product working: the moat did not name a competitor with a structural reason they can't follow. The refusal message tells you what was missing — tighten the audience or pick a more specific URL and run again.

Getting a key, per provider

Every provider below plugs straight in. One difference worth knowing: Anthropic keys are the only ones that run live web research (signals come back with clickable citations). Every other provider cuts the kerf from model knowledge — still structured, still subject to the refusal rule, but without fresh citations.

Model is optional everywhere — leave it blank for the default above, or type any model id your key can access (e.g. gpt-5.1-mini, claude-opus-4-8).

Ollama & local models

Ollama and custom endpoints work with one caveat: the hosted app at kerfbox.vercel.app cannot reach your machine's localhost — the inference call runs from our server, not your browser. Local models need a locally running kerf.box:

git clone https://github.com/12burb/kerfbox
cd kerfbox && pnpm install && pnpm dev
# open http://localhost:3000/app
# provider: Ollama · base URL: http://localhost:11434/v1 · model: llama3.2

The custom provider works the same way for LM Studio, vLLM, LiteLLM, or any other OpenAI-compatible server — point the base URL at your endpoint (the /chat/completions suffix is added automatically). A custom endpoint reachable on the public internet works from the hosted app too.

For agents: MCP and HTTP

The MCP server exposes cut_kerf and generate_copy. Configure it with env vars — provider and model are optional (defaults: anthropic, preset model):

{
  "mcpServers": {
    "kerfbox": {
      "command": "npx",
      "args": ["-y", "kerfbox-mcp"],
      "env": {
        "KERFBOX_BYOK_PROVIDER": "openai",
        "KERFBOX_BYOK_API_KEY": "sk-...",
        "KERFBOX_BYOK_MODEL": "gpt-5.1"
      }
    }
  }
}

Or hit the HTTP API directly — no account, no kerf.box API key, just your provider headers:

curl -N https://kerfbox.vercel.app/api/strategy \
  -H "X-Provider: gemini" \
  -H "X-Api-Key: AIza..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://linear.app","audience":"indie SaaS founders"}'

# Anthropic shorthand (also what kerfbox-mcp <= 0.2 sends):
#   -H "X-Anthropic-Key: sk-ant-..."
# Optional headers: X-Model (any model id),
#   X-Base-Url (custom/ollama endpoints only)

Full schema: /api/openapi.json (OpenAPI 3.1).

When something fails

• “Authentication failed” / 401. The key is missing, malformed, or paired with the wrong provider. Check that the provider dropdown matches the key you pasted — an OpenAI key under “Anthropic” will be rejected before it ever leaves our server.
• “Provider error (404 / model not found)”. The model id isn't available on your key. Clear the model field to use the provider default, or check the exact id in your provider's console.
• “Provider error (429)”. Your provider is rate-limiting or out of credits — that's between you and them; kerf.box adds no metering of its own beyond a per-IP abuse cap.
• The run was refused. Not an error — the moat didn't hold. The message says why. Sharpen the audience line and go again.
• Ollama times out from the hosted app. Expected — see the local models section above. Run kerf.box locally.

Still stuck? File it on the issue tracker.

What happens to my key?

It rides each request as a header, is used once to call your provider, and is never stored, logged, or proxied — the server holds no copy. In the browser it is saved to your device's localStorage only, so you don't re-paste it every visit; clearing the field deletes it. Full details on the privacy page. The entire codebase is open source if you'd rather verify than trust.