Skip to content

Open source alternative to Semrush and Ahrefs

Revise README for clarity and updated information

Ben Senescud24cdc9ac7ed
diff --git a/README.md b/README.md
index 919c6936..2193222a 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,15 @@
# OpenSEO
-OpenSEO is an open source SEO tool for people getting started with SEO, or teams that want something simpler than SEMrush or Ahrefs without paying for another monthly SaaS subscription.
+OpenSEO is an SEO tool for *the people* (non-seo professionals). If tools like Semrush or Ahrefs are too expensive or bloated, OpenSEO is a pay by usage alternative that you actually control.
![OpenSEO demo (placeholder)](https://placehold.co/1200x675?text=OpenSEO+Demo+GIF+Coming+Soon)
## Why Use This
- Open source and self-hostable.
-- No OpenSEO subscription.
-- You own your deployment and data.
+- No subscriptions.
- Focused workflows instead of a giant, complex SEO suite.
+- AI Native - Use your own tools like Claude Code / Cowork for more powerful AI features than what other platforms provide.
## Main SEO Workflows
@@ -17,33 +17,30 @@ OpenSEO is an open source SEO tool for people getting started with SEO, or teams
- Find topics worth targeting, estimate demand, and prioritize what to write next.
- Domain insights
- Understand where your domain is gaining or losing visibility so you can focus on the pages that move revenue.
-- Audits
+- Site Audits
- Catch technical issues early so your site is easier for search engines to crawl and rank.
-## Pricing / Costs
-
-OpenSEO is totally free to use. It works by pulling SEO data from DataForSEO, which is a paid third-party service unaffiliated with OpenSEO.
+## Roadmap
-There are two separate things:
+Top priorities:
-1. OpenSEO app cost: **$0 subscription**.
-2. DataForSEO API usage: pay-as-you-go based on requests.
+- Rank tracking
+- AI content workflows
-As of February 26, 2026, DataForSEO’s public docs/pricing pages say:
+If something important is missing, please join the [Discord](https://discord.gg/c9uGs3cFXr) or email me at [email protected] and request it.
-- New accounts include **$1 free credit** to test the API.
-- The minimum top-up/payment is **$50**.
+## Pricing / Costs
-That means you can try OpenSEO for free with the starter credit, then decide if/when to top up.
+OpenSEO is totally free to use. It works by using DataForSEO's APIs, which is a paid third-party service unaffiliated with OpenSEO.
-For OpenSEO-specific, per-workflow request estimates, see the internal [SEO API Cost Reference](#seo-api-cost-reference).
+There are two separate things:
-For current endpoint pricing and cost calculators, check:
+1. OpenSEO app cost: $0, you host it yourself.
+2. DataForSEO API: pay-as-you-go based on usage.
-- [DataForSEO Pricing](https://dataforseo.com/pricing)
-- [DataForSEO API Documentation](https://docs.dataforseo.com/v3/)
+For cost estimates, see [DataForSEO API Cost Reference](#seo-api-cost-reference).
-## DataForSEO API Key Setup
+## DataForSEO API Key Setup [5 minutes]
OpenSEO expects `DATAFORSEO_API_KEY` as a Basic Auth value.
@@ -59,14 +56,57 @@ Set that output as `DATAFORSEO_API_KEY` in your environment/secrets.
Note: even though the env var is named `DATAFORSEO_API_KEY`, this app sends it as HTTP Basic auth, so the value should be the base64 form of `login:password`.
+## Self Hosting (Deploy on Cloudflare) [5-10 minutes]
+
+OpenSEO is built on [Every App](https://github.com/every-app/every-app), a platform for easily self-hosting open source apps like OpenSEO in your own Cloudflare account. Cloudflare enables much more powerful functionality than is possible running on your own computer or on a VPS.
+
+*Windows Users*
+
+This has not been tested on Windows. Please let me know if you run into problems. Using WSL will likely work better. Also, try using [fly.io Sprites](https://sprites.dev/) to get a linux sandbox for free if you get totally stuck.
+
+### Prerequisites
+If you don't want to make a Cloudflare account yet (its easy!) and just want to test out OpenSEO, skip to the [Run Locally](#seo-api-cost-reference) section.
+
+Note: If you're not comfortable with the terminal or these phrases, ChatGPT or Claude will do a good job coaching you through this.
+
+1. Install [Node.js](https://nodejs.org/) (includes `npx`).
+2. Create a Cloudflare account: [dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up)
+3. Authenticate Wrangler:
+
+```sh
+npx wrangler login
+```
+
+4. Deploy the Every App Gateway (one-time per account):
+
+```sh
+npx everyapp gateway deploy
+```
+
+Follow the link returned by that command to create your gateway account.
+
+### Deploy OpenSEO
+
+```sh
+git clone https://github.com/bensenescu/super-seo.git
+cd super-seo
+npx everyapp app deploy
+```
+
+After deploy, set your DataForSEO secret:
+
+```sh
+npx wrangler secret put DATAFORSEO_API_KEY
+```
+
+When prompted, paste the base64 value of `login:password` (using your DataForSEO login + API password).
+
## Local Development
### Prerequisites
- Node.js 20+
- [pnpm](https://pnpm.io/)
-- A Cloudflare account
-- Every App gateway set up (see [Every App](https://github.com/every-app/every-app))
- A DataForSEO account/API credentials
### Run Locally (Quick Test)
@@ -81,16 +121,20 @@ cp .env.example .env.local
```sh
pnpm install
-pnpm dev
+# This runs in BYPASS_GATEWAY mode so that you don't need to set up the Every App gateway. This is fine for local use.
+pnpm dev:agents
```
App runs on `http://localhost:3001` by default (or `PORT` from `.env.local`).
Running locally is the fastest way to test core flows. In the future, local mode will not include some Cloudflare-backed capabilities (for example cron-based rank tracking and infrastructure-powered performance improvements for heavier audits).
-### Shared Dev Server Workflow (for coding agents)
+### Local Development Workflow (for coding agents)
```sh
+# This log file make it easier for your coding agent to debug.
+mkdir .logs
+touch .logs/dev-server.log
# terminal 1: start once and keep running
pnpm dev:agents
```
@@ -113,54 +157,6 @@ Migrate local DB:
pnpm run db:migrate:local
```
-## Self Hosting (Deploy on Cloudflare)
-
-OpenSEO is built on [Every App](https://github.com/every-app/every-app), a platform for easily self-hosting open source apps in your own Cloudflare account.
-
-### Prerequisites
-
-1. Install [Node.js](https://nodejs.org/) (includes `npx`).
-2. Create a Cloudflare account: [dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up)
-3. Authenticate Wrangler:
-
-```sh
-npx wrangler login
-```
-
-4. Deploy the Every App Gateway (one-time per account):
-
-```sh
-npx everyapp gateway deploy
-```
-
-Follow the link returned by that command to create your gateway account.
-
-### Deploy OpenSEO
-
-```sh
-git clone https://github.com/bensenescu/super-seo.git
-cd super-seo
-npx everyapp app deploy
-```
-
-After deploy, set your DataForSEO secret:
-
-```sh
-npx wrangler secret put DATAFORSEO_API_KEY
-```
-
-When prompted, paste the base64 value of `login:password` (using your DataForSEO login + API password).
-
-## Roadmap
-
-Top priorities right now:
-
-- Rank tracking
-- AI content workflows
-
-If something important is missing, please join the Discord and request it. We prioritize community demand first.
-Discord: [Join the OpenSEO community](https://discord.gg/c9uGs3cFXr)
-
## Contributing
Contributions are very welcome.
@@ -175,6 +171,13 @@ If you want to contribute but are unsure where to start, open an issue and descr
Use this section to estimate DataForSEO spend per request type. OpenSEO itself remains free; these are API usage costs only.
+As of February 26, 2026, DataForSEO’s public docs/pricing pages say:
+
+- New accounts include **$1 free credit** to test the API.
+- The minimum top-up/payment is **$50**.
+
+That means you can try OpenSEO for free with the starter credit, then decide if/when to top up.
+
### Pricing sources
- DataForSEO Labs pricing: https://dataforseo.com/pricing/dataforseo-labs/dataforseo-google-api