The setup wizard, step by step

The wizard starts the first time you open your dashboard. It checks each step on the spot and saves your progress as you go: close the tab whenever, and it reopens exactly where you stopped.

On dispatchseo.com (the hosted version)

The hosted setup is a setup path: one step on the screen at a time, about 5 minutes in all, because the platform does the installing for you. Every step waits for proof that it's done - GitHub sends you back, your AI reaches us, Google says yes - and only then moves on. You don't tick anything off by hand, and you can't skip a step by accident. Reload the page or come back tomorrow and you land on the same step.

Which steps you see depends on the two answers you gave when you signed up: where finished articles go (a WordPress site you host yourself, a site built from a GitHub repo, or "I'll place them myself"), and which AI writes them (the ordinary Claude app at claude.ai, Claude Code, Codex, or Cursor). You aren't asked them again.

The setup screen

1. "What's your website?" Type your domain - for example yoursite.com - and press Continue. Under the field, one line repeats your two signup answers, for example "WordPress site · written by the Claude app". If either is wrong, click change and pick again. That's the whole first step.

2. Connect your site. Which step you get depends on where articles go.

   • A GitHub repo: "Install the DispatchSEO GitHub App". Click Install on GitHub. You land on GitHub's own install page: choose Only select repositories, pick the one repo your site is built from, and press Install. GitHub sends you straight back. If you shared more than one repo, the next step asks "Which repo is your site?" - pick it once. Repo in an organization? An owner may have to approve the install; the page re-checks on its own. There are no tokens to create or paste.
   • WordPress: "Connect your WordPress". The step asks for your WordPress address, a username and an application password, and shows you how to make one in your own WordPress admin: go to Users and add a new user called DispatchSEO with the role Editor (your own account works too, but a separate one is easier to switch off later), open that user, scroll to Application Passwords, type DispatchSEO as the name and click Add, then copy the password it shows - WordPress only shows it once. The step checks the password against your site before it turns green. Nothing gets installed on the site itself.
   • "I'll place them myself": there's no step here.

3. Connect your AI. There are three versions, depending on your answers.

   • The Claude app: "Connect your Claude app". Click Copy the connector address. Open claude.ai in a browser (not the phone app - the setting is only on the website), click your name at the bottom left, then Settings, then Connectors. Click Add custom connector, name it DispatchSEO, and paste the address as the URL. That address is a password: anyone who has it can read and change your site's content plan, so don't post it anywhere. The step turns green on its own the moment your Claude first reaches us - there is no button to press. Expect claude.ai to ask you to allow each DispatchSEO tool the first time it uses it: choose Always allow.

   • A coding agent, articles go to a repo: "Give Claude Code a key to your repo" (or Codex, or Cursor). For Claude Code, run this in a terminal and paste what it prints:

     claude setup-token
     

     Copy

     For Codex, paste an OpenAI API key from platform.openai.com/api-keys (it starts with sk-, and the account needs credit on it). For Cursor, paste an API key from cursor.com/dashboard/api - open that address directly; any plan can make one. Press Save the key. It's stored as a secret on your repo, never on our side, and builds run on your own subscription or key.

   • A coding agent, no repo: "Connect Claude Code to this site" (or Codex, or Cursor). Open a terminal in an empty folder for your SEO work, click Copy the command, paste it into the terminal and press Enter. Then open your agent in that folder and type:

     Say hello to DispatchSEO
     

     Copy

     The step turns green on its own the moment your agent reaches us. Nothing is stored anywhere.

   Don't have an agent yet? Install Claude Code, Codex, or Cursor first - about five minutes. The key and connect steps can't turn green until you have.

4. "Connect Google Search Console". Click Connect Google, sign in with the Google account that manages your site in Search Console, and allow the read-only access Google asks for. You come straight back. If we can't match your site to a property on that account, one more step asks "Which Search Console property is yoursite.com?" - pick it and it saves on the spot. Site not in Search Console at all yet? See Google Search Console.

5. "You're connected." Click Open your dashboard.

Claude app plus a GitHub repo is the one combination that skips the GitHub step here. Your Claude does the writing and DispatchSEO opens the pull request, so the GitHub App install comes later, as the first step on Home, titled "Let us publish to your repo". It works the same as described in step 2.

You're never asked about publish mode during setup. Every site starts in Semi: nothing goes live until you merge it. Prefer hands-off? Flip the Semi / Auto switch in the dashboard's top bar, any time.

"I'll do this later"

Some steps have a small I'll do this later link under them: connecting WordPress, connecting the Claude app, connecting a coding agent with no repo, and Search Console. Click it and the step is parked - "Parked. It'll come back as your next step on Home." - and the path moves on. The "You're connected" screen lists anything you parked.

The GitHub App, the repo pick and the agent key can't be parked: without them nothing can be written or published.

A parked step doesn't disappear. It comes back as the one thing to do on Home whenever the rest of setup is only waiting on something, and setup doesn't count as finished until it's done.

After you connect: the next-step card on Home

The dashboard opens with a card at the top of Home showing the one thing left to do. Every other dashboard page has a single line linking back to it. The card is either a step for you or a wait: "Nothing for you to do. This turns green on its own.", with how long it's been running and how long it usually takes. If a wait runs much longer than usual, the card says so and links to where you can look.

For a coding agent and a GitHub repo, the card goes through these, in order (each one only shows up if it applies):

1. "Installing your pipeline…" - automatic. If it fails, the card shows why and a Try again button.
2. "Merge the install pull request" - only if your repo needs the install to go in as a pull request. Click Open the PR and press Merge on GitHub.
3. "One GitHub toggle needs your click" - see the paragraph below.
4. "Your agent is learning your site" - a wait, usually 5-15 minutes.
5. "Researching your first keywords" - a wait, usually 10-20 minutes.
6. "Approve the ideas you like" - click Open the Queue and approve one or two. Nothing is written until you do. (Skipped in Auto.)
7. "Pulling your first rankings" - a wait, usually a few minutes.
8. "Writing your first article" - a wait. Approved ideas are written overnight, after midnight UTC.
9. "Merge your first article" - click Open Pages, read it, press Merge. In Auto this is a wait instead: "Publishing your first article".

For the Claude app, or a coding agent with no repo, the card gives you one sentence at a time to paste to your AI, each with a Copy button:

1. "Let it learn your business" - your AI asks three short questions about your business. A sentence each is plenty.
2. "Ask it for article ideas" - it queues a handful, each with a one-line reason.
3. "Approve the ideas you like" - on the Queue screen.
4. "Ask it to write the first one".
5. "Checking and publishing your article" - a wait. If you place articles yourself, the article is ready on the Drafts screen with a Copy button.

When the first article is live and nothing is parked, the card goes away. Keyword data is included in your plan - there is nothing to set up for it.

If your articles go to a repo, there is one thing the App can't do for you. It deliberately holds no permission to change your repo's own settings, and some repos have GitHub's "Allow GitHub Actions to create and approve pull requests" turned off - which stops DispatchSEO opening the pull requests it publishes through. When that's the case, the card on Home says so with a direct link to the setting. Flip it once; it re-checks on its own and unblocks, so there's nothing to come back and confirm.

The rest of this page describes the self-hosted wizard, which has a few more steps because your own install does the work the platform does on the hosted version.

Step 1 - Add your site

Name and domain of your website - the site you want Google traffic for, not the machine DispatchSEO runs on. Then one question that decides the rest of the form: where do finished articles get published?

• A GitHub repo - your site is built from code. A field appears for the repo, which is the owner/repo part of its GitHub URL, followed by one more question: does your site have a blog? "Not sure" is a valid answer - Claude checks the repo and decides during setup.
• WordPress - WordPress you host yourself (not wordpress.com). That's the whole answer: no repo field, no GitHub account needed. You connect the site itself on step 6.

Step 2 - Connect Google Search Console

This is where your ranking and traffic numbers come from. DispatchSEO reads them through a service account - a robot Google account that it signs in as. You create one once and it works for every site you ever add.

The wizard walks you through it with direct links: create a Google Cloud project, enable the Search Console API, create the service account, download its key file, and paste the file's contents into the wizard. The key is stored encrypted in your own database.

Then you add the service account's email as a user in Search Console (the wizard shows the exact clicks) and press Verify connection - it asks Google right then and tells you if it worked. Google occasionally takes a few minutes to catch up; you can continue and it re-checks on its own.

This is the fiddliest step in the whole setup, and the only one that leaves the app. If you want every click spelled out - including what to do when your site isn't in Search Console yet and you need to add a DNS record to prove you own it - Google Search Console is the same walkthrough at full length.

Step 3 - Pick a keyword data source

Two choices, switchable later in Settings:

• DataForSEO (paid, recommended): real Google search volumes and difficulty scores - the same data most SEO tools resell. Pay as you go; a typical site costs $2-5/month, and new accounts get $1 free.
• Free mode ($0 forever): Claude finds opportunities in your own Search Console data and Google's autocomplete suggestions. If you go free, the wizard offers one optional upgrade: a free SerpApi key (250 searches/month, no credit card) that lets Claude look at the real Google results page before writing, to judge whether a keyword is winnable.

Whatever you pick, the wizard verifies the credentials against the real service before saving them.

Step 4 - Coding agent

One choice: Claude Code, Codex, or Cursor. All three do the same job here - research, writing, pull requests - the difference is who bills you. Claude Code runs on a Claude subscription you already pay for; Codex runs on your own OpenAI API key, metered per run; Cursor runs on your Cursor plan's API key. DispatchSEO never bills you for agent usage in any case.

Everything after this adapts to your pick: the finish line's pastes come ready for the agent you chose. You can still change your mind on the finish screen, or any time later from the dashboard's top bar.

Step 5 - Publish mode

Should anything go live without you?

• Semi-automatic (recommended to start): Claude researches and builds on its own, but you approve ideas and click Merge on finished pages. A few minutes of your attention a week.
• Automatic: everything runs itself; pages that pass their checks publish without anyone touching them. You can watch and undo from the dashboard.

There's a Semi/Auto toggle in the dashboard's top bar, so this is never a final answer.

Step 6 - Connect GitHub

This is step 6 if you picked a GitHub repo on step 1. WordPress sites get Connect WordPress here instead.

Claude ships pages as GitHub pull requests, and this step gives DispatchSEO a GitHub token so it can work with them. The wizard links you to a pre-filled GitHub page, you press Generate, paste the token, and it's verified against your repo before saving (encrypted, like everything else).

Whether you can skip it depends on your install. On a hosted install (Vercel), the pipeline runs as GitHub Actions inside your own repo, so your pages get built and the pull requests open either way - the token only adds one-tap merging, and skipping just means you merge each PR on GitHub yourself.

On a Docker install using the bundled builder, the token is how the builder reaches your repo at all: it clones with it. Skip it and nothing gets built - there are no pull requests waiting for you on GitHub, because none were ever opened. The skip button is still there for the one case that needs it (a Docker install on a public URL that lets GitHub-hosted workflows do the building instead), but for everyone else on Docker, this step is required.

One thing GitHub asks that the wizard can't answer for you: the token's expiration. Whatever you pick, merging quietly stops working on that date, and on a Docker install so does automatic building. Pick a window you'll actually remember, or choose No expiration and treat the token like the password it is. When it does expire, nothing breaks loudly - you just come back to this step and paste a new one.

Step 6 - Connect WordPress

This is step 6 if you picked WordPress on step 1. Three fields: your site's address, the username you log in to WordPress with, and an application password. That last one is not your login password - it's a separate one WordPress makes for you: in your WordPress admin open Users, then Profile, scroll to Application Passwords, type DispatchSEO as the name and press Add New Application Password. Copy what it shows and paste it into the wizard.

The wizard checks it against your site on the spot and tells you what's wrong if anything is - most often that the user is a Subscriber and needs to be an Editor or Administrator to publish. Nothing gets installed on your site, and the password is stored encrypted in your own database.

You can skip this and connect later from Settings. Until you do, finished articles wait on the Drafts screen rather than getting lost.

Step 7 - The honest timeline

A month-by-month picture of what SEO actually looks like, so a quiet first month reads as "on schedule" instead of "broken". Just read it.

The finish line: two pastes

WordPress sites get a shorter version of this screen, because there's no repo to install anything into:

1. A terminal command that connects your coding agent to this project. Make an empty folder for your SEO work and run it there - the connection belongs to that folder, so always open your agent in it.
2. A chat message to paste into the agent. It learns your site and fills your queue with article ideas.
3. A second chat message for whenever you want an article written: approve ideas on the Queue screen, paste it, and the finished article is checked, formatted and posted to your WordPress.

Only your coding agent needs to be installed for these - not the GitHub CLI. One difference to know about: a WordPress site has no automatic overnight builds. Articles get written when you ask your agent for one, so the Docker "automatic builds" item below doesn't appear.

The rest of this section is the GitHub repo version. The last screen gives you two things to copy:

1. A terminal command that connects your coding agent to this project. Run it inside your site's repo folder.
2. A chat message to paste into the agent itself (open the repo, type claude or codex, paste). This one does the actual install.

Both come pre-adapted to the agent you picked on step 4, and the same screen lets you switch agents if you've changed your mind.

From that second paste, your agent takes over: it writes the automation workflow files into your repo, sets the repo secrets, opens one pull request with all of it, personalizes the backlink playbook for your product, and kicks off your first keyword research. You approve its steps in the chat as it goes. It's safe to re-run if anything is interrupted.

Both pastes assume your coding agent and the GitHub CLI (gh) are already on your computer. If they aren't - or if a command comes back command not found - it's a one-time detour: Claude Code and gh in about five minutes, or Codex plus gh from cli.github.com.

Docker installs get one more item on the same screen: turning on automatic builds. One credential, minted for whichever agent you picked - claude setup-token on your own computer for Claude Code, an API key from platform.openai.com/api-keys for Codex, or an API key from cursor.com/dashboard/api for Cursor - pasted into the field on this same screen (no terminal on the server needed). The wizard's checklist flips green when the builder makes its first check-in.

Which key is which

Setup hands you four different secrets (the last one depends on which agent you picked), and they look alike enough to mix up. You never have to memorize or file any of them - the dashboard shows each one again wherever it's needed - but when you're staring at a field wondering which string goes in it:

All of them are stored encrypted in your own database.

Live progress, and what "stuck" actually looks like

The wizard tracks all of it live. When the pipeline PR is open, it shows "Your move: merge the pipeline PR" with a direct link - merging that PR is your one required click. The agent then verifies the full checklist (workflows on the main branch, permissions, labels, secrets) and reports back over MCP; the backend double-checks it independently. The dashboard only unlocks once everything genuinely works. If the wizard says it's still waiting, the agent isn't done yet - check its chat.

When a step won't pass

Some of setup depends on things this page can't check for you: whether Google has verified your property yet, or what your repo's workflow permissions are set to. If a step keeps failing and Troubleshooting doesn't cover it, ask in the Discord. Say which step you're on and paste what the screen tells you. Your progress is saved, so you can close the tab and pick up at the same step once you have an answer.