Documentation

SeoSmart Self-Hosted docs

Install and run SeoSmart on your own Cloudflare account. New here? See what Self-Hosted includes.

Requirements

  • A license key (it arrives by email after purchase).
  • A Cloudflare account on Workers Paid ($5/month).
  • A domain added to that account and Active. SeoSmart uses the whole domain (for example yourseo.com).
  • A Postgres database. Supabase or Neon free tiers are enough to start.
  • Node.js 22 or newer (Windows, macOS or Linux), only to run the installer.
  • An OpenRouter API key for AI writing. Every other key is optional.

Install

Open a terminal and run:

npx seosmart@latest

The installer asks for:

  1. License key, from your purchase email.
  2. Domain, already active on Cloudflare.
  3. Postgres connection string. In Supabase: Connect > URI > Session pooler (port 5432), then put your password in place of [YOUR-PASSWORD].
  4. Cloudflare API token. Use the link the installer prints (permissions are preselected), pick the account that holds your domain, create the token and paste it.

It creates everything in Cloudflare, sets up the database and deploys SeoSmart. Running it again is safe: existing resources are kept. Settings are saved in ~/.seosmart/state.json.

After install

  1. Open https://your-domain/setup and create your owner account.
  2. Set up email in Settings > Email so password resets and invites work.
  3. Create a project and add its OpenRouter key under Project Settings > Integrations.

Commands

Run these from the computer you installed from.

npx seosmart@latestInstall, or reinstall with your saved answers.
npx seosmart@latest updateDeploy the newest release with your saved settings.
npx seosmart@latest statusShow your domain, version and whether the site answers.
npx seosmart@latest domainRedo DNS and customer blog domain setup.
npx seosmart@latest license deactivateFree your license to move it to another domain.
npx seosmart@latest uninstallDelete the Workers. Your database and files are kept.

Updates

Your dashboard shows a notice when a new release is out. To update:

npx seosmart@latest update

Your data, settings and secrets are kept. See the changelog.

API keys

Keys are saved per project and encrypted in your database. You pay each provider directly. Add only what you use.

OpenRouter (AI writing, required)

In SeoSmart: Project Settings > Integrations > AI

  1. Create an account at openrouter.ai and add credits under Settings > Credits.
  2. Open Keys, create a key and copy it (it starts with sk-or-).
  3. Paste it in the project. Every AI feature of that project now uses it.
openrouter.ai/settings/keys

DataForSEO (keyword volumes, SERPs, audits)

In SeoSmart: Project Settings > Integrations > DataForSEO

  1. Sign up at dataforseo.com and add funds (pay as you go).
  2. Open API Access in the dashboard and copy your API login and API password.
  3. Paste both in the project.
app.dataforseo.com/api-access

ScreenshotOne (website screenshots)

In SeoSmart: Project Settings > Integrations > ScreenshotOne

  1. Sign up at screenshotone.com (there is a free tier).
  2. Copy the Access key and the Secret key from the dashboard.
  3. Paste both in the project.
dash.screenshotone.com/access

Serper or Tavily (web search for research)

In SeoSmart: Project Settings > Integrations > Web search

  1. Serper: sign up at serper.dev and copy the API key (2,500 free searches).
  2. Tavily: sign up at tavily.com and copy the API key (free monthly credits).
  3. Add either one; SeoSmart uses whichever is set.
serper.dev

Google app (Search Console)

In SeoSmart: Project Settings > Integrations > Google Search Console

  1. In Google Cloud Console, create a project and enable the Google Search Console API.
  2. Configure the OAuth consent screen, then create an OAuth client ID of type Web application.
  3. Copy the redirect URL shown in SeoSmart into Authorized redirect URIs, then paste the Client ID and Client secret back in SeoSmart.
console.cloud.google.com/apis/credentials

Shopify app (publish to Shopify stores)

In SeoSmart: Publishing > Websites & CMS > Shopify

  1. In the Shopify Dev Dashboard, create an app.
  2. Copy the App URL, scopes and redirect URL that SeoSmart shows into the app settings.
  3. Paste the app's Client ID and Client secret in SeoSmart, then connect your store.
dev.shopify.com/dashboard

Email

Set up SMTP in Settings > Email, then click Send test email. Zoho Mail works on the free plan: host smtp.zoho.com (or smtp.zoho.eu), port 587, your mailbox and an app password. Use port 465 or 587 only.

Blog domains

In Project > Blog > Domain, add the domain. In that domain's DNS, point a CNAME to sites.your-domain (ALIAS or ANAME for a root domain). HTTPS is issued automatically.

Custom domains need Cloudflare for SaaS on your SeoSmart domain (first 100 hostnames free). If you skipped it during install, enable it under SSL/TLS > Custom Hostnames, then run:

npx seosmart@latest domain

License

  • One license runs one install on one domain. All self-hosted updates are included.
  • To move domains, run npx seosmart@latest license deactivate (or free it from Manage license), then install on the new domain.
  • Lost your key? Open Manage license with the email from checkout and generate a new one, then run the installer with it.

Backups

  • Keep a private copy of ~/.seosmart/state.json. It holds the secrets your install needs, including the key that encrypts your API credentials.
  • Back up your Postgres database (Supabase and Neon both offer backups).
  • Media files live in the seosmart-media R2 bucket in your Cloudflare account.

Troubleshooting

Every installer run writes a log to ~/.seosmart/logs. Attach the latest one when you ask for help.

Cloudflare refused the CPU limit, or Workflows need Workers Paid

Upgrade the Cloudflare account to Workers Paid ($5/month) under Workers & Pages > Plans, then run the installer again.

Your Cloudflare token is missing a permission

Create a new token with the link the installer prints (every permission is preselected), pick the account that holds your domain, and run the installer again.

Cloudflare has no zone for your domain

Add the domain to Cloudflare, wait until it is Active, and make sure the token was created on that same account.

The database connection fails

With Supabase, use the Session pooler string (port 5432) from Connect > Connection String. If the password has symbols like @ # / ?, encode them or reset it to letters and digits.

This license is already used on its maximum number of domains

One license runs one install. Run npx seosmart@latest license deactivate on the old install, or free it from the Manage license page, then install again.

The site does not answer right after install

Cloudflare can take a minute or two for HTTPS and DNS. Wait, then open https://your-domain/setup. Run npx seosmart@latest status to check.

Emails are not sent

Set up SMTP in Settings > Email and click Send test email. Use port 465 or 587 (not 25).

Getting help

Write to info@seosmart.app or ask on Discord. Attach the latest log from ~/.seosmart/logs.