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@latestThe installer asks for:
- License key, from your purchase email.
- Domain, already active on Cloudflare.
- Postgres connection string. In Supabase: Connect > URI > Session pooler (port 5432), then put your password in place of
[YOUR-PASSWORD]. - 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
- Open
https://your-domain/setupand create your owner account. - Set up email in Settings > Email so password resets and invites work.
- Create a project and add its OpenRouter key under Project Settings > Integrations.
Commands
Run these from the computer you installed from.
npx seosmart@latest | Install, or reinstall with your saved answers. |
npx seosmart@latest update | Deploy the newest release with your saved settings. |
npx seosmart@latest status | Show your domain, version and whether the site answers. |
npx seosmart@latest domain | Redo DNS and customer blog domain setup. |
npx seosmart@latest license deactivate | Free your license to move it to another domain. |
npx seosmart@latest uninstall | Delete 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 updateYour 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
- Create an account at openrouter.ai and add credits under Settings > Credits.
- Open Keys, create a key and copy it (it starts with sk-or-).
- Paste it in the project. Every AI feature of that project now uses it.
DataForSEO (keyword volumes, SERPs, audits)
In SeoSmart: Project Settings > Integrations > DataForSEO
- Sign up at dataforseo.com and add funds (pay as you go).
- Open API Access in the dashboard and copy your API login and API password.
- Paste both in the project.
ScreenshotOne (website screenshots)
In SeoSmart: Project Settings > Integrations > ScreenshotOne
- Sign up at screenshotone.com (there is a free tier).
- Copy the Access key and the Secret key from the dashboard.
- Paste both in the project.
Serper or Tavily (web search for research)
In SeoSmart: Project Settings > Integrations > Web search
- Serper: sign up at serper.dev and copy the API key (2,500 free searches).
- Tavily: sign up at tavily.com and copy the API key (free monthly credits).
- Add either one; SeoSmart uses whichever is set.
Google app (Search Console)
In SeoSmart: Project Settings > Integrations > Google Search Console
- In Google Cloud Console, create a project and enable the Google Search Console API.
- Configure the OAuth consent screen, then create an OAuth client ID of type Web application.
- Copy the redirect URL shown in SeoSmart into Authorized redirect URIs, then paste the Client ID and Client secret back in SeoSmart.
Shopify app (publish to Shopify stores)
In SeoSmart: Publishing > Websites & CMS > Shopify
- In the Shopify Dev Dashboard, create an app.
- Copy the App URL, scopes and redirect URL that SeoSmart shows into the app settings.
- Paste the app's Client ID and Client secret in SeoSmart, then connect your store.
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 domainLicense
- 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-mediaR2 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
Your Cloudflare token is missing a permission
Cloudflare has no zone for your domain
The database connection fails
This license is already used on its maximum number of domains
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
Emails are not sent
Getting help
Write to info@seosmart.app or ask on Discord. Attach the latest log from ~/.seosmart/logs.