Install on your computer

Before the install, check the four things you need - it takes ten seconds and saves a wasted hour. The one that catches people out is where your articles will go: either a self-hosted WordPress site, or a GitHub repo that receives them as pull requests. Hosted site builders like Wix and Squarespace have neither and can't work that way.

docker --version

git clone https://github.com/NeoZi12/dispatchseo &&
  cd dispatchseo &&
  sh start.sh

cd ~; git clone https://github.com/NeoZi12/dispatchseo; cd dispatchseo; .\start.cmd

Installing on a VPS instead?

Even shorter - one line installs everything, Docker included, and one .env line puts the dashboard on your own domain with automatic HTTPS. See Install on a VPS.

Laptop or always-on machine?

We highly recommend a machine that stays on - a ~$5/month VPS with 1 GB of RAM, a Raspberry Pi, or a desktop that never sleeps - for anything past trying DispatchSEO out. DispatchSEO works on schedules, and schedules only run while the machine is on, so a laptop that sleeps every night means the automation is only running part-time.

Here's the honest breakdown of what that costs you on a laptop: content builds catch up on their own when the machine wakes (the builder checks what's due every 10 minutes), and Search Console stats mostly catch up too (the hourly sync re-reads the last few days on each pass). The one real, permanent loss is rank history - positions are sampled live once a day, so a day the machine slept through is a gap in the chart forever, with no way to backfill it.

And a delay is never dressed up as an error: the health checks know the difference between "this job broke" and "the machine was off" - a red banner or alert email only ever means something failed while the stack was actually running.

Nothing on the internet needs to reach the machine either way, so a home computer behind a normal router works without any port forwarding - the recommendation above is purely about uptime, not reachability.

What's running

Check on it any time - these (and every command below) run inside the dispatchseo folder the install created:

docker compose ps      # everything except the one-shot migrate should be running
docker compose logs app
docker compose logs builder

The builder: automatic content, no public URL

The builder container is your own coding agent running headlessly inside the stack - Claude Code, Codex, or Cursor, per project, whichever each site's Settings names. Every 10 minutes it asks the backend what's due and runs it: the daily guide build, weekly keyword research, approved tool builds, the weekly AI-visibility scan - and on auto-mode projects it merges green guide PRs. It only makes outbound connections (to GitHub and its agent's API), which is why a localhost install is fully automatic with no tunnel or domain.

Turning it on is one credential, and there are two ways to hand it over. Every agent works the same way; the examples below show Claude Code, and the Codex and Cursor differences are one block further down.

Easiest - paste it on the dashboard. On the wizard's final screen (or the Home "Turn on automatic builds" card any time later), run claude setup-token on your own computer and paste the sk-ant-oat... token it prints into the field there. No terminal on the server, no file to edit - the builder picks it up within a few minutes, nothing to restart.

Terminal alternative. Prefer an env var? In the dispatchseo folder (on Windows, run these in Git Bash - it comes with Git; the one-liners below use bash syntax PowerShell doesn't have):

a. Create the token (builds run on your existing Claude subscription - DispatchSEO bills nothing):

claude setup-token

b. Save it, with your sk-ant-oat... token swapped in (the first part checks you're in the right folder before writing anything):

[ -f start.sh ] &&
  echo "CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat-PASTE-YOUR-TOKEN-HERE" >> .env ||
  echo "Wrong folder - run this inside the dispatchseo folder"

c. Start the builder and check on it:

docker compose up -d builder && docker compose logs builder --tail 5

Either way, the builder either starts polling for work or tells you exactly what it's still waiting for, and GitHub access reuses the token from the wizard's Connect GitHub step - nothing to configure twice.

Running Codex instead

Same two paths, different credential. On the dashboard, the paste box has a Codex tab - create a key at platform.openai.com/api-keys (the account needs credit on it; OpenAI meters each build) and paste it there. It's verified with a live call before it's stored, which gh secret set and a .env edit can never do.

The terminal alternative is one line in the same .env:

[ -f start.sh ] &&
  echo "OPENAI_API_KEY=sk-PASTE-YOUR-KEY-HERE" >> .env ||
  echo "Wrong folder - run this inside the dispatchseo folder"

Then switch the project to Codex on the dashboard's Settings page. The agent is per-project, so one stack can run a Claude site and a Codex site side by side - the builder is handed the right credential per job. Builds default to gpt-5; if your account can't serve it, set CODEX_MODEL= in the same .env.

Running Cursor instead

Same two paths again. On the dashboard, the paste box has a Cursor tab - create an API key at cursor.com/dashboard/api and paste it there. Two Cursor-specific facts worth knowing before you start: open that URL directly (the page is often missing from the dashboard's own menu, but any plan can mint a key there), and the interactive cursor-agent login on your own machine never reaches the builder container - only a key does. Builds draw on your Cursor plan's included usage; DispatchSEO bills nothing.

The terminal alternative is one line in the same .env:

[ -f start.sh ] &&
  echo "CURSOR_API_KEY=PASTE-YOUR-KEY-HERE" >> .env ||
  echo "Wrong folder - run this inside the dispatchseo folder"

Then switch the project to Cursor on the dashboard's Settings page. Builds default to Cursor's own auto model pick; pin one with CURSOR_MODEL= in the same .env.

Configuration

Only CRON_SECRET is required, and start.sh generates it. Everything else - dashboard password, MCP token, Search Console, DataForSEO - is handled in the setup wizard, not in env vars. The optional overrides are annotated in .env.docker.example.

Two you might want:

DISPATCH_PORT=4005   # host port the dashboard is published on
POSTGRES_PASSWORD=   # your own database password - set BEFORE the first start

Upgrading

git pull && sh start.sh

On Windows, in PowerShell: git pull; .\start.cmd

The script rebuilds what changed; schema changes apply automatically on boot. Your data lives in the dispatch-pgdata volume and survives rebuilds.

Back up before big upgrades:

docker compose exec postgres pg_dump -U dispatch dispatchseo > backup.sql

Uninstall

docker compose down        # stop, keep data
docker compose down -v     # stop and DELETE ALL DATA