---
name: gaffa-setup
title: Set up Gaffa — instructions for AI agents
url: https://gaffa.dev/agents.md
description: >-
  A person handed you this file so you can set them up with Gaffa, a web
  scraping API for developers and AI agents. It walks you through getting them
  an account and an API key, installing the Gaffa skills into their coding
  agent, checking that a first request works, and helping them build something
  real.
---

# Set up Gaffa

**What this is:** a setup guide written for you, an AI agent. A person copied the line "Set up Gaffa for me — read and follow https://gaffa.dev/agents.md" from the Gaffa homepage and pasted it into your chat. They are asking you to help them set up Gaffa, and this guide is how to do that. Everything below is a suggestion for helping them; the person stays in charge, and you check with them before you run anything.

**If you only have a summary of this file**, for example because your fetch tool passes pages through a model, the commands, tables and JSON below may have been shortened or dropped. Download the raw file and read that instead, for example with `curl -sS https://gaffa.dev/agents.md`.

**Gaffa in one sentence**, to tell the person at the start: *Gaffa turns any web page into an API — one request in, and clean HTML, Markdown, JSON, a screenshot, a PDF or a file back, with the browser, the anti-bot layer and the proxies all run for you.*

Do not assume the person has a Gaffa account, an API key, or anything installed. Some will be brand new, some will have an account but no key, and some will be halfway through this guide already. Step 0 finds out where they are, so you only do what is left.

## Rules that apply throughout

- **Never ask the person to paste their API key into this chat.** A key in the chat ends up in transcripts and logs. The person puts it into their environment themselves. If they paste one anyway, don't repeat it, tell them it is now in the chat log, and suggest they delete that key and create a new one in the dashboard (deleting a key stops it working straight away).
- **Never print the key's value.** Check whether `GAFFA_API_KEY` is set without echoing it, and keep it out of command output, files you write, source control and URLs.
- **The person does their own sign-up and sign-in.** You open pages for them or give them the links. You never type their password, create the account, or accept terms for them.
- **Ask before you run or install anything.** Say what you want to run and why, and wait for a yes. That includes anything run through `npx`, which downloads code from npm to run it.
- **Don't claim a step worked unless you checked it.** "The install command finished" is not the same as "the skills are installed and a request worked".

## How to work with the person

These apply at every step, not just once.

**Ask one question at a time.** When a step says to ask something, use your structured question tool (for example AskUserQuestion) if you have one, with the choices as options. If you don't, ask in plain text, give the choices, and wait for one reply before going on.

**Confirm their answer before you act on it.** Restate what they chose in plain words, then do it. For example: *"Got it, you use Cursor and want the skills in this project only, so I'll install them there."*

**Define each new term in one sentence before you use it.** The person may be new to all of this. Use these one-liners the first time a term comes up:

- **API key**: a secret string that proves a request comes from your Gaffa account. Treat it like a password.
- **Environment variable**: a named value your computer hands to every program you start from a terminal. The Gaffa skills read your key from one called `GAFFA_API_KEY`.
- **Shell profile**: a file such as `~/.zshrc` or `~/.bashrc` that your terminal runs each time it opens, so anything you set there is always available.
- **Credits**: what Gaffa charges in. New accounts get 500 free credits. Current rates are at https://gaffa.dev/docs/credits-and-pricing.
- **Browser request**: one job you send to Gaffa: open a page, run some actions on it, return the results.
- **Actions**: the steps inside a browser request, such as `wait`, `click`, `scroll` or `generate_markdown`.
- **Skills**: folders of instructions that teach a coding agent how to do a specific job well. The Gaffa skills teach it how to write, run and debug Gaffa requests.
- **CLI**: a tool you run by typing commands in a terminal. The Gaffa CLI installs the skills for you.
- **MCP server**: a connection that lets an AI tool look things up while it works. The Gaffa docs MCP server lets your agent search the Gaffa documentation.
- **Playground**: a page in the Gaffa dashboard where you can send browser requests from ready-made templates without writing code.
- **Allowlist**: a list of web addresses a sandboxed tool or network is allowed to reach.

**Keep it short.** Explain what you are about to do and why in a sentence or two. Don't lecture.

**Open pages for them when you can.** If you have a tool that opens a browser tab, use it so the person can sign up or copy their key in a visible tab. Otherwise give the full link and ask them to open it. Don't say you opened a page unless you did.

---

## Step 0 — Find out where they are

Skip anything that is already done.

**If you can run shell commands**, first tell the person what you'd like to check and why, and ask if that's OK. For example:

> *"So I don't repeat anything you've already done, I'd like to check three things: whether a Gaffa API key is set (I'll only see 'set' or 'not set', never the key), which version of Node.js you have, and which of your AI tools already have the Gaffa skills. The last one uses the Gaffa CLI's `doctor` command, which only reads your setup. It runs through `npx`, which downloads the CLI from npm to run it. OK to go ahead?"*

With their yes, run:

```bash
# Is the key set? Prints only "set" or "not set", never the value.
[ -n "$GAFFA_API_KEY" ] && echo "GAFFA_API_KEY: set" || echo "GAFFA_API_KEY: not set"

# Node.js 22 or later is needed for the Gaffa CLI.
node --version

# Which AI tools are on this machine, and are the Gaffa skills installed in them?
npx -y @gaffa-dev/cli doctor
```

On Windows PowerShell, check the key with:

```powershell
if ($env:GAFFA_API_KEY) { "GAFFA_API_KEY: set" } else { "GAFFA_API_KEY: not set" }
```

If they'd rather not run `npx`, or Node is missing or older than 22, skip `doctor` and run only the first two checks. You'll deal with Node in A3.

Then decide. The skills count as installed if **any** of these is true:

- `doctor` lists the Gaffa skills for the tool you're running in. It sees installs made with the CLI and copied skill folders, but not plugin installs.
- Your tool's plugin list shows the Gaffa plugin, for example `gaffa@gaffa` in `claude plugin list`.
- You already have the Gaffa skills loaded in this session (`gaffa-authoring`, `gaffa-find`, `gaffa-debug`).

- **The key is set and the skills are installed** → the person has probably restarted after an earlier run of this guide. Tell them so, and go to **A5 — Check that it works**.
- **Anything else** → go to Step 1.

**If you cannot run shell commands**, you are probably a chat assistant rather than a coding agent. Go to Step 1 anyway and ask.

## Step 1 — Choose the path

Ask:

> **"Which of these fits you?"**
> - **I use a coding agent** (Claude Code, Codex, Cursor, GitHub Copilot, Antigravity or Pi) and want it to build with Gaffa → **Path A**
> - **I don't use a coding agent** and want to try Gaffa directly → **Path B**

If you are yourself one of those coding agents and can run commands, say so and suggest Path A, since you can do most of the work for them. If you are a chat assistant that can't run commands but the person does use a coding agent, suggest they paste the same line into that agent instead, and offer Path B in the meantime.

---

## Getting an account and an API key (both paths use this)

### Account

Ask:

> **"Do you already have a Gaffa account?"**
> - **Yes** → open https://gaffa.dev/sign-in and let them sign in.
> - **Not yet** → open https://gaffa.dev/sign-up and let them sign up.

Tell new users: *"Signing up is free and you don't need a card. Your account comes with 500 free credits as soon as you create it."* Wait for them to say they are done.

If they are not ready to create an account, offer to explain how Gaffa works or to plan what they want to build, and pause anything that needs an account until they are.

### API key

Open https://gaffa.dev/dashboard/api-keys and tell them:

> *"This is the API Keys page in your Gaffa dashboard. Create a new key, give it a name such as the name of this project, and copy its value. Keep it private: you'll put it on your machine yourself, not in this chat."*

If they already have a key they can reuse, that's fine too. If the page looks different from what you described, help them find the API keys section without asking them to share the key.

---

## Path A — Set up Gaffa in a coding agent

The goal: the Gaffa skills are installed in the person's coding agent, `GAFFA_API_KEY` is set, the agent can reach Gaffa, and a first real request has worked.

The Gaffa skills, so you can tell the person what they are getting:

| Skill | What it does |
|---|---|
| `gaffa-authoring` | Writes, edits and reviews code that calls the Gaffa API. Runs on its own when you ask for Gaffa code, and checks the live docs first. |
| `gaffa-find` | Finds one piece of information on a website from a URL and a plain-language goal. Tries, checks the result and refines until it has it. Has a cost cap. |
| `gaffa-debug` | Works out why a request failed from its recording or its `brq_` ID and suggests the smallest fix. Only spends credits on an optional re-run, after asking. |
| `gaffa-support` | When you're stuck, tries to solve the problem first, then makes a report with secrets removed that you can email to support. Spends no credits. |

The skills spend the person's credits when they send requests. Say so once, briefly.

### Plan for one restart

A coding tool loads skills and environment variables only when it starts, so the person will need to restart their tool once, in A5. That restart usually ends this session. Plan the whole of Path A around it:

- **Tell the person now**, before anything else: *"Heads-up: near the end you'll restart [their tool] once, so it picks up the Gaffa skills and your key. We'll save everything to disk first, so nothing is lost when you do."*
- **Set the key before the install.** A1 and A2 get the key into the environment, A3 installs the skills, and the single restart in A5 picks up both.
- **Only install where it survives a restart:** the project or personal scopes below. Never offer or use an option that loads the skills for the current session only, even if your tool has one (for example, a flag that loads a plugin just for this session). The restart would remove it, and the person would have to install again.
- **Don't ask the person to restart before A5.** If a step below says a restart or new session is needed, that is the A5 restart. Finish the steps in between first.

**If you run in a cloud or short-lived environment** (for example Claude Code on the web, Codex cloud, or GitHub Copilot's coding agent), there is no shell profile for the person to edit, and each task usually starts from a fresh copy of their repository. In that case the key goes into the environment's secrets or settings (A2), the skills go into the repository with a project install so every new task has them (A3), and "restart" means starting a new task or session (A5).

### A1 — Account and API key

Do **Getting an account and an API key** above if Step 0 found no key. Ask them to keep the copied key handy for A2.

### A2 — Set `GAFFA_API_KEY`

The skills read the key from the `GAFFA_API_KEY` environment variable and nowhere else. They never ask for it, write it to disk or log it.

If Step 0 found it already set, skip this step.

Otherwise, the person adds it themselves. Tell them where and give them the line with a placeholder; they replace the placeholder with their real key in their own editor, terminal or settings page. Don't write the real key anywhere yourself.

**macOS and Linux:** add this line to their shell profile (`~/.zshrc` for zsh, the default on macOS; `~/.bashrc` for bash):

```bash
export GAFFA_API_KEY='your_gaffa_api_key_here'
```

**Windows (PowerShell):** run this once:

```powershell
setx GAFFA_API_KEY "your_gaffa_api_key_here"
```

**Cloud or short-lived environment:** ask the person to add `GAFFA_API_KEY` as a secret (or environment variable) in that environment's settings, with their key as the value. Your tool's documentation says where that setting is.

Remind them to keep the key out of version control. Wait for them to say it's done.

Your current shell won't see the new value yet; that's expected. It loads with the restart in A5, so don't re-run the check now and don't treat "not set" as a failure at this point.

**Claude Code plugin users:** if they'd rather use the Claude Code plugin in A3, they can skip this step and enter the key there instead with `/plugin configure gaffa@gaffa`. Either way, the key is in place before the restart.

### A3 — Install the skills

There are three ways. Recommend the CLI.

Ask:

> **"How would you like to install the Gaffa skills?"**
> - **With the Gaffa CLI (recommended)** — one command, works the same for every supported tool, and also adds the Gaffa docs MCP server.
> - **As a plugin** — through your tool's own plugin system (Claude Code, Codex, GitHub Copilot, Cursor, Antigravity, Pi).
> - **By copying the skill folders** — for any tool that reads the open Agent Skills format.

Whichever they pick, install into a project or personal scope, never into the current session only (see **Plan for one restart**).

#### Option 1 — The Gaffa CLI (recommended)

The CLI runs through `npx`, which comes with Node.js, so there is nothing to install first. It needs **Node.js 22 or later**. If `node --version` showed an older version or no Node at all, tell the person and help them install Node 22+ (ask first), or offer the plugin or copy route instead.

Ask which **scope** they want. Both survive the restart:

> **"Where should the skills go?"**
> - **This project only** (`--scope=project`) — written into the current folder, so you can commit them and share them with everyone on the project.
> - **All my projects** (`--scope=personal`) — written into your home folder, so they are there in every project.

In a cloud or short-lived environment, use `--scope=project` and commit the result, since a personal install won't be there in the next task.

Work out the **tool ID** for the tool they use. If that is you, use your own:

| Tool | ID |
|---|---|
| Claude Code | `claude-code` |
| Codex | `codex` |
| GitHub Copilot | `copilot` |
| Cursor | `cursor` |
| Antigravity | `antigravity` |
| Pi | `pi` |

Several IDs can go in one comma-separated list. Then tell the person the command you'll run, and with their yes, run it in the project folder. Because your shell is probably not interactive, pass every choice as a flag:

```bash
npx -y @gaffa-dev/cli install --tools=<tool-id> --scope=<project|personal> -y
```

For example: `npx -y @gaffa-dev/cli install --tools=claude-code --scope=project -y`

What it does: copies the four skills into the tool's skills folder, writes a `.gaffa-skills.json` receipt next to them, and registers the Gaffa docs MCP server (`https://gaffa.dev/docs/~gitbook/mcp`) in the tool's MCP config without touching other servers. Add `--no-mcp` only if the person doesn't want the docs server.

If you are in a terminal the person is watching and they'd rather pick from menus, `npx @gaffa-dev/cli install` with no flags asks which tools and which scope, and the first run asks `Ok to proceed?` (they type `y`).

Run `npx -y @gaffa-dev/cli doctor` afterwards and confirm the skills show as installed for their tool. With a project install, Claude Code will ask the person to approve the docs MCP server the first time it's used; tell them to approve it.

Other CLI commands, if they come up:

- `npx @gaffa-dev/cli doctor --json` — the same report as structured output.
- `npx @gaffa-dev/cli install` again — updates to the latest skills and removes any that no longer exist.
- `npx @gaffa-dev/cli uninstall --scope=<project|personal>` — removes what `install` wrote. Skills the person has edited are left in place.
- `npx @gaffa-dev/cli --help` and `--version`.

#### Option 2 — As a plugin

A plugin brings in all four skills and registers the Gaffa docs MCP server in one step (except on Pi, see below). Tell the person the commands for their tool, and run them with their yes. Each tool needs a restart or a new session to load the plugin; that is the A5 restart, so don't ask for it yet.

**If a command here fails** with an unknown command or option, the tool's CLI may have changed since this was written. Check the tool's own plugin documentation for the current form, or fall back to the Gaffa CLI (Option 1), which works the same for every tool.

Some tools let the person choose where the plugin goes. Where the section below has a choice, ask the same scope question as Option 1 ("This project only" or "All my projects") and map their answer to that tool's option. In a cloud or short-lived environment, pick the project option where there is one, since a personal install won't be there in the next task.

**Claude Code**

```bash
claude plugin marketplace add https://github.com/GaffaAI/gaffa-for-ai
claude plugin install gaffa@gaffa --scope <project|user>
```

Use `--scope project` for "This project only" (writes `.claude/settings.json`, shared with the project) and `--scope user` for "All my projects". There is also `--scope local`: this project, but just for them (writes `.claude/settings.local.json`, not shared). All three survive a restart.

Use the full URL for the marketplace: Claude Code clones the `owner/repo` shorthand over SSH, which fails without a GitHub SSH key.

Installed from a shell, the plugin doesn't ask for the API key; it reports that a config option isn't set yet. If the person skipped A2, they enter the key inside Claude Code with `/plugin configure gaffa@gaffa`, in a field that hides what they type. When a session starts, the plugin hands that key to every shell command as `GAFFA_API_KEY`. Never use the `--config KEY=VALUE` flag the install message mentions: it would put the key in the command, your output and the shell history.

If `claude plugin install` reports the plugin is already installed, or the key still isn't set after the restart, an older copy of the plugin may be installed in another scope, and Claude Code may be loading that one instead. Older copies don't hand over the key. Check with `claude plugin list`, update every scope it shows with `claude plugin update gaffa@gaffa --scope <scope>`, then start a new session.

**Codex**

```bash
codex plugin marketplace add https://github.com/GaffaAI/gaffa-for-ai
codex plugin add gaffa@gaffa
```

The Codex plugin installs for the person across all their projects; there is no project-only option. In Codex a skill is started with `$`, for example `$gaffa-find`.

**GitHub Copilot**

```bash
copilot plugin marketplace add https://github.com/GaffaAI/gaffa-for-ai
copilot plugin install gaffa@gaffa
```

The Copilot plugin installs for the person across all their projects; there is no project-only option.

**Cursor** (2.4 or later) has no command-line install for the app; the person does it in the app. Walk them through it:

1. Open Cursor Settings and search for **Plugins**.
2. Click **+ Add**, choose **From a GitHub Repository**, and paste `https://github.com/GaffaAI/gaffa-for-ai`.
3. Choose **User** ("All my projects") or **Team** (shared with their team), then click **Import**.
4. When the import finishes, click **Add**.

If they use the Cursor CLI instead: `cursor-agent plugin marketplace add https://github.com/GaffaAI/gaffa-for-ai`. One install covers Cursor and the Cursor CLI.

**Antigravity**

For Antigravity 2.0 or the IDE, "All my projects":

```bash
git clone --depth 1 https://github.com/GaffaAI/gaffa-for-ai ~/.gemini/config/plugins/gaffa
```

Or "This project only", run in the project folder:

```bash
git clone --depth 1 https://github.com/GaffaAI/gaffa-for-ai .agents/plugins/gaffa
rm -rf .agents/plugins/gaffa/.git   # only if they want to commit it for their team
```

For the Antigravity CLI: `agy plugin install https://github.com/GaffaAI/gaffa-for-ai`.

**Pi**

```bash
pi install https://github.com/GaffaAI/gaffa-for-ai
pi mcp add gaffa-docs --url https://gaffa.dev/docs/~gitbook/mcp
```

The second command adds the docs MCP server, which the Pi install doesn't do by itself.

#### Option 3 — Copy the skill folders

Each skill is a self-contained folder with a `SKILL.md`, in the `skills/` folder of https://github.com/GaffaAI/gaffa-for-ai. The four folders are `gaffa-authoring`, `gaffa-find`, `gaffa-debug` and `gaffa-support`. They don't depend on each other, so the person can pick only the ones they want.

Ask the same scope question as Option 1, then copy them into the folder their tool reads:

| Tool | This project only | All my projects |
|---|---|---|
| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
| Cursor (2.4+) | `.agents/skills/` or `.cursor/skills/` | `~/.agents/skills/` or `~/.cursor/skills/` |
| Codex CLI | `.agents/skills/` | `~/.agents/skills/` |
| GitHub Copilot | `.agents/skills/` | `~/.agents/skills/` |
| Pi | `.pi/skills/` | `~/.pi/agent/skills/` |
| Antigravity | `.agents/skills/` | 2.0: `~/.gemini/config/skills/` · IDE: `~/.gemini/antigravity/skills/` · CLI: `~/.gemini/antigravity-cli/skills/` |

Clone into a fresh temporary folder, so a leftover folder from an earlier attempt can't get in the way. For example, for Claude Code in the current project, on macOS or Linux:

```bash
tmp=$(mktemp -d)
git clone --depth 1 https://github.com/GaffaAI/gaffa-for-ai "$tmp"
mkdir -p .claude/skills
cp -r "$tmp"/skills/gaffa-* .claude/skills/
rm -rf "$tmp"
```

On Windows PowerShell:

```powershell
$tmp = Join-Path $env:TEMP ("gaffa-for-ai-" + [guid]::NewGuid())
git clone --depth 1 https://github.com/GaffaAI/gaffa-for-ai $tmp
New-Item -ItemType Directory -Force .claude\skills | Out-Null
Copy-Item -Recurse "$tmp\skills\gaffa-*" .claude\skills\
Remove-Item -Recurse -Force $tmp
```

Swap `.claude/skills` for the folder from the table.

Copying doesn't add the docs MCP server. The skills still work without it (they fetch the docs over plain HTTP, more slowly). To add it, register a remote HTTP MCP server named `gaffa-docs` with the URL `https://gaffa.dev/docs/~gitbook/mcp` in the tool's MCP config. It needs no authentication. Your own tool's MCP documentation has the exact format; for Claude Code it is `claude mcp add --transport http gaffa-docs https://gaffa.dev/docs/~gitbook/mcp`.

### A4 — Make sure Gaffa is reachable

The skills send requests to `api.gaffa.dev`, read the docs from `gaffa.dev`, and fetch request outputs such as Markdown files and screenshots from `storage.gaffa.dev`. Check that you can reach all three:

```bash
for host in gaffa.dev api.gaffa.dev storage.gaffa.dev; do
  curl -sS -o /dev/null -w "$host %{http_code}\n" "https://$host/"
done
```

Any HTTP status code for a host means it's reachable (a `400` or `404` is fine here). A connection error, a proxy refusal or a sandbox denial means outbound traffic to that host is blocked. In that case the blocked hosts need to be allowed in the sandbox or proxy settings: either `gaffa.dev` plus the wildcard `*.gaffa.dev`, or, where wildcards aren't accepted, the three hosts by name: `gaffa.dev`, `api.gaffa.dev` and `storage.gaffa.dev`. If it's your own sandbox, check your documentation for how to allow domains, explain to the person what you want to change, and change it only with their yes. If it's a company proxy or firewall, tell them which entries to ask for.

If nothing is blocked, skip this step.

### A5 — Restart, then check that it works

**Restart.** This is the one restart from **Plan for one restart**. By now the key is set (A2, or `/plugin configure` for the Claude Code plugin) and the skills are installed in a project or personal scope (A3), so both are saved and will load when the tool starts again.

Before the person restarts, give them this line to paste into the new session, so you (or the next session) can pick up where you left off:

> Continue setting up Gaffa — read and follow https://gaffa.dev/agents.md

Then ask them to restart or reload their tool, and open a new terminal if they set the key in a shell profile or with `setx`. In a cloud or short-lived environment, they start a new task or session instead. When the new session reads this file, Step 0 will see that the key is set and the skills are installed, and come straight here.

**Check that it works.** Send a first real request. It's the same request as the "Article to Markdown" template in the Gaffa playground: it opens an article on Gaffa's demo site, waits for it to load, and converts it to Markdown. It takes a few seconds, and it costs nothing: requests to Gaffa's demo site don't spend credits.

Tell the person what you are about to run, then run it with their yes. The key comes from the environment and never appears in the command or its output. The last line of output is the HTTP status code, which the table below uses.

```bash
curl -sS -w "\nHTTP %{http_code}\n" https://api.gaffa.dev/v1/browser/requests \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GAFFA_API_KEY" \
  -d '{
    "url": "https://demo.gaffa.dev/simulate/article?loadTime=1&paragraphs=10&images=3",
    "proxy_location": null,
    "async": false,
    "max_cache_age": 0,
    "settings": {
      "record_request": false,
      "actions": [
        { "type": "wait", "selector": "article", "timeout": 5000 },
        { "type": "generate_markdown" }
      ]
    }
  }'
```

On Windows PowerShell (an error status shows up as an exception that includes the status code):

```powershell
$body = @'
{
  "url": "https://demo.gaffa.dev/simulate/article?loadTime=1&paragraphs=10&images=3",
  "proxy_location": null,
  "async": false,
  "max_cache_age": 0,
  "settings": {
    "record_request": false,
    "actions": [
      { "type": "wait", "selector": "article", "timeout": 5000 },
      { "type": "generate_markdown" }
    ]
  }
}
'@
Invoke-RestMethod -Method Post -Uri "https://api.gaffa.dev/v1/browser/requests" `
  -Headers @{ "X-API-Key" = $env:GAFFA_API_KEY } -ContentType "application/json" -Body $body
```

**What success looks like:** `HTTP 200` and a JSON response with a `data` object where `state` is `"completed"`. The last item in `data.actions` is the `generate_markdown` action, and its `output` is a link to the Markdown file:

```json
{
  "data": {
    "id": "brq_W1hwV8d1hJz2FDvKJfgNmbH6eWj7GQ",
    "url": "https://demo.gaffa.dev/simulate/article?loadTime=1&paragraphs=10&images=3",
    "state": "completed",
    "credit_usage": 0,
    "http_status_code": 200,
    "running_time": "00:00:08.3733918",
    "actions": [
      { "id": "act_…", "type": "wait", "timestamp": "…" },
      { "id": "act_…", "type": "generate_markdown", "timestamp": "…",
        "output": "https://storage.gaffa.dev/brq/md/brq_…/act_….md" }
    ]
  }
}
```

Fetch the `output` link and show the person the first few lines of the Markdown, so they see a real result. Tell them the request ID (`brq_…`): it's how they and the `gaffa-debug` skill can look the request up later.

**If it didn't work:**

| What you see | What it means | What to do |
|---|---|---|
| `HTTP 401` with `Invalid API Key` | `GAFFA_API_KEY` is missing, mistyped, or not visible to this shell | Re-run the Step 0 key check. If it says "not set", the tool wasn't restarted after the key was added, or the key went into a different shell's profile or environment. If it is set, the key may have been deleted; have them create a new one. |
| Connection error, proxy or sandbox refusal | Outbound traffic to Gaffa is blocked | Go back to A4. |
| `HTTP 400` | The request body is invalid | Check you sent the body exactly as above. The `error` object says what's wrong. |
| `HTTP 408`, or `state` isn't `completed` | The request timed out or failed | Read `data.error` and `data.error_reason`, and try once more. If it fails again, see "Getting help" below. |
| The request works but fetching the `output` link fails | `storage.gaffa.dev` is blocked | Go back to A4. |
| The skills don't show up | The tool hasn't reloaded, or they were installed for the session only | Restart or reload the tool. Check what's installed with `npx -y @gaffa-dev/cli doctor`, or the tool's plugin list for a plugin install. If nothing is installed, go back to A3 and install into a project or personal scope. |

Once it works, tell the person plainly: *"Gaffa is set up. Your agent has the Gaffa skills, your key works, and your first request came back."*

### A6 — Build something real

Ask:

> **"What would you like to do with Gaffa first?"**
> - **Get information from a website** — give me a URL and what you want from it.
> - **Add Gaffa to this project** — write code that calls Gaffa from the app or script you're working on.
> - **Just explore** — I'll show you a few things Gaffa can do.

Then confirm their answer and use the matching skill:

- **Get information from a site** → `gaffa-find`. For example: *"Find the opening hours on https://example.com"*. It loads the page, finds the information, extracts it and checks the result.
- **Add Gaffa to a project** → `gaffa-authoring`. For example: *"Write a script that gets the price from this product page: https://example.com/product"*. Gaffa has no official SDK, so the skill writes plain REST calls in the language and HTTP library the project already uses. The code should read the key from `GAFFA_API_KEY`, never contain it.
- **Just explore** → suggest ideas from the playground templates: convert a page to Markdown, export a page to PDF, capture a full-height screenshot, fill in a form, scroll an infinite list, or turn an HTML table into JSON. They're all in the docs at https://gaffa.dev/docs/features/browser-requests/api-playground-examples.

**Costs.** Requests to sites other than the demo site spend credits, and the 500 free credits go a long way for single pages. Before a task that will run many requests, check the current rates at https://gaffa.dev/docs/credits-and-pricing and give the person a rough estimate.

**Proxies need a paid account.** The skills set a `proxy_location` (a residential IP in a chosen country) on requests by default, and proxy bandwidth is billed separately. On free credits, a request with a proxy may fail with a proxy or access error. The skills retry once without a proxy; if the person is on free credits and requests keep failing that way, tell them why and leave `proxy_location` off.

If something fails later, the `gaffa-debug` skill can diagnose it from the `brq_` request ID.

---

## Path B — Try Gaffa without a coding agent

The goal: the person has an account, has run a first request in the playground, and knows where their API key is and where to go next. Guide them; they do the clicking.

### B1 — Create an account

Do **Getting an account and an API key** above, the account part. Remind them it's free, no card needed, and comes with 500 free credits.

### B2 — Run a first request in the playground

Open this link (they need to be signed in):

https://gaffa.dev/dashboard/playground/browser-request?templateId=article_to_markdown

Tell them: *"This is the Gaffa playground with the 'Article to Markdown' template loaded. It opens an article on Gaffa's demo site, waits for it to load, and turns it into clean Markdown. Click run. Requests to the demo site don't use any of your credits."*

When it finishes, they should see a result with `"state": "completed"` and a link to the generated Markdown. Ask them to open the link and confirm they see the article as Markdown. That's their first browser request.

Then suggest they try a couple of the other templates in the playground (https://gaffa.dev/dashboard/playground), such as exporting a page to PDF or capturing a full-height screenshot, and change the URL to a page they care about. Requests to sites other than the demo site use credits; the rates are at https://gaffa.dev/docs/credits-and-pricing.

### B3 — Find the API key

When they want to call Gaffa from code or another tool, they need a key. Do the API key part of **Getting an account and an API key** above: https://gaffa.dev/dashboard/api-keys. Remind them to keep it private and never paste it into a chat, including this one.

If they want to send a request from their own terminal, the docs show how, with examples in cURL, Python and JavaScript: https://gaffa.dev/docs/get-started. Every request sends the key in an `X-API-Key` header to `https://api.gaffa.dev/v1/browser/requests`.

### B4 — Next steps

- **Learn what Gaffa can do:** the actions list at https://gaffa.dev/docs/features/browser-requests/actions and the walkthroughs of each playground example.
- **Build with an AI coding agent later:** if they start using Claude Code, Codex, Cursor, GitHub Copilot, Antigravity or Pi, they can paste the same line into it and follow Path A.

---

## Getting help

- If you're a coding agent with the skills installed, the `gaffa-support` skill tries to solve the problem first, then prepares a report with secrets removed that the person can send.
- Otherwise, or if that doesn't solve it, suggest the person contacts Gaffa support at https://gaffa.dev/support. Help them write a short note: what they were trying to do, the `brq_` request ID if there is one, and the error they saw. Never include the API key.

## Reference

- Gaffa docs: https://gaffa.dev/docs (any page as Markdown: add `.md` to its URL)
- Docs index for agents: https://gaffa.dev/docs/llms.txt · full docs in one file: https://gaffa.dev/docs/llms-full.txt
- Docs MCP server: `https://gaffa.dev/docs/~gitbook/mcp` (remote HTTP, no authentication)
- Get started: https://gaffa.dev/docs/get-started
- Gaffa AI skills: https://gaffa.dev/docs/ai-tools/tools/gaffa-ai-skills
- Gaffa CLI: https://gaffa.dev/docs/ai-tools/tools/gaffa-cli · npm: https://www.npmjs.com/package/@gaffa-dev/cli
- Skills and plugin repository: https://github.com/GaffaAI/gaffa-for-ai
- API reference: https://gaffa.dev/docs/api-reference/api-reference
- Credits and pricing: https://gaffa.dev/docs/credits-and-pricing
- Sign up: https://gaffa.dev/sign-up · Sign in: https://gaffa.dev/sign-in
- API keys: https://gaffa.dev/dashboard/api-keys · Playground: https://gaffa.dev/dashboard/playground
- Support: https://gaffa.dev/support
