# The setup wizard, step by step > What each wizard screen asks for, why, and what to do when a step gets stuck. Source: https://dispatchseo.com/docs/setup-wizard All docs in one file: https://dispatchseo.com/llms-full.txt 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 wizard is shorter - about 5 minutes - because the platform does the installing for you. It also branches: the first screen asks where your articles should go and which AI will write them, and your two answers decide which screens you see after that. 1. **Add your site** - name and domain, then the two questions. Where do finished articles go: a WordPress site you host yourself, a GitHub repo, or neither yet? And which AI will write them: the ordinary Claude app at claude.ai, Claude Code, Codex, or Cursor? There is no repo field here; the repo comes from the GitHub App on the next screen if you pick that answer. 2. **Connect WordPress**, or **Connect GitHub** - which screen you get depends on the first answer. For **WordPress**: your site's address, the username you log in with, and an application password. The screen shows you where to generate one (in your own WordPress admin: Users, then Profile, then Application Passwords) and checks it against your site before it lets you past. Nothing gets installed on the site itself. For a **GitHub repo**: one click installs the DispatchSEO GitHub App on it, and the platform then commits the pipeline into the repo and manages PRs through the App - no tokens to create or paste. If you answered "neither yet", this screen doesn't appear at all. 3. **Connect the Claude app**, or **Connect your coding agent** - three shapes, and you get the one your answers point at. If your AI is the **Claude app**, the screen gives you one address to paste into claude.ai under Settings, then Connectors, as a custom connector, plus the sentence to send in a new chat so your Claude introduces itself to the site. A light on the screen turns green on its own the moment your Claude 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 - and expect Claude to ask you three short questions about your business; a sentence each is plenty. From then on the Home screen's "Your next step" list tells you which sentence to paste next and which screen to open. If it's a **coding agent and your articles go to a repo**, you paste the credential the agent asks for (`claude setup-token` for Claude Code, an OpenAI API key for Codex, a Cursor API key from cursor.com/dashboard/api for Cursor). 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 with no repo** gets one connect command to run in a terminal, and stores nothing anywhere. Don't have an agent yet? Install [Claude Code](/docs/install-claude-code), [Codex](/docs/install-codex), or [Cursor](/docs/install-cursor) first - about five minutes, and this step won't pass until you have. 4. **Connect Google Search Console** - one click, sign in with the Google account that has access to your property, pick the property. Read-only, revocable any time. No service account needed. You can skip it and come back later; everything else works without it, you just have no traffic numbers until it's connected. 5. **Publish mode** - decide whether pages go live only after you approve them (semi-automatic) or fully on their own. Then the finale does the rest itself and shows live progress until your site's first data lands - on the repo path, that includes installing the pipeline. 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 finale says so with a direct link to the setting. Flip it once; the checklist 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, domain, and GitHub repo of **your website** - the site you want Google traffic for, not the machine DispatchSEO runs on. The repo is the `owner/repo` part of its GitHub URL. Then one question: does your site have a blog? "Not sure" is a valid answer - Claude checks the repo and decides during setup. ## 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](/docs/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 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 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 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](/docs/install-claude-code) in about five minutes, or [Codex](/docs/install-codex) plus gh from [cli.github.com](https://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](https://platform.openai.com/api-keys) for Codex, or an API key from [cursor.com/dashboard/api](https://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: | Key | Starts with | What it's for | Where it comes from | | --- | --- | --- | --- | | Agent key (MCP token) | a long random string | How your coding agent talks to this dashboard | Generated for you; already inside the connect command the wizard hands you. Also on Settings. | | Cron key | a long hex string | Lets the scheduled jobs call your backend | Generated for you; the install sets it as a repo secret. You never paste it by hand. | | GitHub token | `ghp_` | Lets the Approve button merge your pull requests | You create it on GitHub in step 6. | | Claude Code token | `sk-ant-oat` | Docker only, if you picked Claude Code - lets the bundled builder run it for you | You create it by running `claude setup-token` on your own computer. | | OpenAI API key | `sk-` | Docker only, if you picked Codex - lets the bundled builder run it for you | You create it at [platform.openai.com/api-keys](https://platform.openai.com/api-keys); the account needs credit on it. | | Cursor API key | `crsr_` | Docker only, if you picked Cursor - lets the bundled builder run it for you | You create it at [cursor.com/dashboard/api](https://cursor.com/dashboard/api) (open that URL directly - the page is often missing from the dashboard's own menu). | 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](/docs/troubleshooting) doesn't cover it, ask in the [Discord](/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.