How to Configure and Run OpenSEO Locally for Development

To configure and run OpenSEO locally, enable Corepack to activate pnpm, install dependencies with frozen lockfile, migrate the local Cloudflare D1 database, configure your DataForSEO API key in .env.local, and launch the dev server using either pnpm run dev or pnpm dev:agents for agent-friendly access.

OpenSEO is a modern TypeScript-based SEO platform that uses Node.js 20+ and Cloudflare D1 (SQLite) for local development. Configuring the project requires specific environment variables for external APIs and authentication modes that mirror production while enabling rapid iteration. This guide walks through the exact steps to get a fully functional instance running locally, based on the official source code in the every-app/open-seo repository.

Prerequisites and System Requirements

Before cloning the repository, ensure your environment meets the baseline requirements. OpenSEO requires Node.js 20 or higher and uses pnpm (version 10.30.1 as pinned in package.json) as its package manager.

You must also obtain a DataForSEO account and generate a base-64 encoded token from your login:password credentials. This API key powers the platform's SEO data retrieval capabilities.

Project Setup and Package Manager Activation

The repository uses Corepack to enforce the exact pnpm version recorded in package.json, preventing dependency drift across environments.

First, enable Corepack to activate the pinned package manager:

corepack enable

Then install dependencies using the frozen lockfile to guarantee exact version matching:

pnpm install --frozen-lockfile

This command respects pnpm-lock.yaml and ensures consistent dependency trees across all developer machines.

Database Preparation and Migration

OpenSEO defaults to Cloudflare D1 (SQLite) for local development. Before running the application, you must initialize the local database schema using the provided migration script.

Run the local migration command from the project root:

pnpm run db:migrate:local

This command applies the Drizzle ORM migrations located in src/db/ to your local D1 instance. You only need to run this once per fresh clone or after schema changes. For PostgreSQL-backed setups, refer to the alternative configuration in docs/LOCAL_POSTGRES.md.

Environment Configuration

The application relies on environment variables defined in .env.local. Copy the example template to create your local configuration:

cp .env.example .env.local

Edit .env.local to include your DataForSEO API key and authentication mode:

# Required: Base64-encoded DataForSEO credentials

DATAFORSEO_API_KEY=$(printf 'your_login:your_password' | base64)

# Recommended for local development

AUTH_MODE=local_noauth

The AUTH_MODE variable controls user validation. Set it to local_noauth to bypass authentication and automatically inject an admin user (admin@localhost), which is ideal for rapid local development without configuring external identity providers.

Running the Development Server

OpenSEO provides two distinct methods to start the local development server, defined in package.json.

Standard Vite Development

For quick UI previews and standard development:

pnpm run dev

This launches the Vite development server in standard mode, suitable for manual browser testing.

Agent-Friendly Development Mode

For AI agent integration and enhanced logging:

mkdir -p .logs
pnpm dev:agents

This command starts the application through portless, a zero-config reverse proxy, and streams logs to .logs/dev-server.log. The server runs at http://open-seo.localhost:1355 and automatically prefixes URLs with the current git branch name when working in worktrees, making it the recommended entry point for automated tooling and agent-based workflows according to docs/LOCAL_DEVELOPMENT.md.

Understanding Authentication Modes

The AUTH_MODE environment variable determines how OpenSEO validates user sessions. The source code supports three distinct modes:

• local_noauth – Bypasses authentication entirely, injecting a mock admin user. This is the default recommendation for local development to eliminate external dependency requirements.
• cloudflare_access – Validates Cloudflare Access JWTs, used in production deployments behind Cloudflare Zero Trust.
• hosted – Enables BetterAuth email/password authentication flow, requiring additional secrets for email providers and callback URLs.

Development scripts do not automatically set AUTH_MODE, so you must explicitly declare it in .env.local to experiment with non-default authentication flows.

Docker Self-Hosting Alternative

For containerized local development, OpenSEO includes a Docker Compose configuration:

docker compose up -d

The docker-compose.yaml automatically sets AUTH_MODE=local_noauth, providing a zero-config containerized environment that persists data and respects the same environment variable patterns as the native Node.js setup.

Summary

• Enable Corepack (corepack enable) to activate the pinned pnpm version 10.30.1 declared in package.json.
• Install dependencies using pnpm install --frozen-lockfile to ensure reproducible builds.
• Initialize the database by running pnpm run db:migrate:local to set up the Cloudflare D1 schema.
• Configure environment variables in .env.local, including a base64-encoded DATAFORSEO_API_KEY and AUTH_MODE=local_noauth.
• Start the server using either pnpm run dev for standard development or pnpm dev:agents for AI-agent-friendly access at http://open-seo.localhost:1355.

Frequently Asked Questions

What Node.js version does OpenSEO require?

OpenSEO requires Node.js 20 or higher. The project uses modern JavaScript features and relies on Corepack (bundled with Node.js 24, available separately in Node.js 20) to manage the pnpm package manager version.

Why does my DataForSEO API key need to be base64 encoded?

The DataForSEO API uses HTTP Basic Authentication, which requires the login:password string to be base64 encoded before being sent in the Authorization header. The application expects this pre-encoded value in the DATAFORSEO_API_KEY environment variable to match the API's authentication protocol.

Can I use PostgreSQL instead of Cloudflare D1 for local development?

Yes. While Cloudflare D1 is the default for local development, the repository includes PostgreSQL configuration instructions in docs/LOCAL_POSTGRES.md. The Drizzle ORM migrations in src/db/ support both SQLite (D1) and PostgreSQL dialects.

What is the difference between pnpm run dev and pnpm dev:agents?

pnpm run dev starts the standard Vite development server for manual browser testing. pnpm dev:agents launches the application through portless with automatic branch-based URL prefixing and logs streamed to .logs/dev-server.log, specifically designed for AI agent integration and automated development workflows.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}