# How to Run a Local Development Environment for OpenSEO: Complete Setup Guide

> Run OpenSEO locally with this complete setup guide. Install dependencies, configure your environment, and launch the development server for efficient coding and testing. Get started now.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: getting-started
- Published: 2026-06-28

---

**To run a local development environment for OpenSEO, install Node 20+ and pnpm, execute `pnpm install` and `pnpm run db:migrate:local`, configure your `.env.local` file with Base64-encoded DataForSEO credentials, then launch the server with `pnpm run dev` or `pnpm dev:agents` for enhanced logging.**

Setting up a local development environment for OpenSEO requires configuring a **Node 20+** stack with **pnpm** as the package manager and preparing a local SQLite database compatible with Cloudflare D1. The every-app/open-seo repository provides npm scripts in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json) that automate database migrations and Vite server startup. This guide walks through the exact commands and configuration files needed to get the dev server running at `http://open-seo.localhost:1355`.

## Prerequisites and Initial Setup

OpenSEO depends on modern Node.js features and requires specific tooling before installation.

### Install Node 20+ and pnpm

Ensure your system runs **Node.js version 20 or higher**. Install **pnpm** globally to handle workspace dependencies:

```bash
npm i -g pnpm@10

```

Clone the repository and install all workspace packages:

```bash
git clone https://github.com/every-app/open-seo.git
cd open-seo
pnpm install

```

The `install` command processes dependencies defined in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json), which contains scripts for `"dev": "vite dev"` and other essential commands【/cache/repos/github.com/every-app/open-seo/main/package.json#L8-L13】.

## Database Migration

OpenSEO uses a Cloudflare D1-compatible SQLite database for local development. You must initialize this database before running the application.

Run the local migration script once after cloning:

```bash
pnpm run db:migrate:local

```

This script executes `wrangler d1 migrations apply DB --local` as defined in [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json) under the `"db:migrate:local"` key【/cache/repos/github.com/every-app/open-seo/main/package.json#L24-L26】. The command creates and configures the local SQLite file that stores application data during development.

## Environment Configuration

Create a local environment file to store API credentials and configuration variables:

```bash
cp .env.example .env.local

```

Edit `.env.local` to add your **DataForSEO API key**. This value must be Base64-encoded in the format `login:password`:

```bash

# Generate the Base64 string

printf '%s' 'mylogin:mypassword' | base64

# Output: bXlsb2dpbjpteXBhc3N3b3Jk

```

Paste the result into `.env.local`:

```bash
DATAFORSEO_API_KEY=bXlsb2dpbjpteXBhc3N3b3Jk

```

The documentation in [`docs/LOCAL_DEVELOPMENT.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md) details this requirement on lines 18-24, emphasizing the Base64 encoding requirement for the DataForSEO integration【/cache/repos/github.com/every-app/open-seo/main/docs/LOCAL_DEVELOPMENT.md#L18-L24】.

## Starting the Development Server

OpenSEO offers two modes for running the local development server: standard Vite mode and the recommended agents mode with enhanced logging.

### Standard Development Server

Run the basic Vite development server:

```bash
pnpm run dev

```

This executes `vite dev` directly and serves the application on the default port.

### Agents Mode (Recommended)

For a superior development experience with stable hostnames and file logging, use the agents script:

```bash
pnpm dev:agents

```

This command expands to `mkdir -p .logs && portless run vite dev 2>&1 | tee .logs/dev-server.log`, which creates a `.logs` directory and streams output to `.logs/dev-server.log` while exposing the app at `http://open-seo.localhost:1355`【/cache/repos/github.com/every-app/open-seo/main/package.json#L11-L13】. The **portless** utility adds a stable hostname and eliminates port conflicts, as documented in [`docs/LOCAL_DEVELOPMENT.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md) lines 27-38【/cache/repos/github.com/every-app/open-seo/main/docs/LOCAL_DEVELOPMENT.md#L27-L38】.

When using git worktrees, the server automatically maps to `http://<branch>.open-seo.localhost:1355`.

## Authentication Mode Configuration

By default, local development sets `AUTH_MODE=local_noauth`, bypassing Cloudflare Access checks for immediate access.

To test Cloudflare Access integration locally, override the authentication mode:

```bash
AUTH_MODE=cloudflare_access pnpm run dev

```

The [`docs/LOCAL_DEVELOPMENT.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md) file on lines 58-66 describes the supported authentication modes and when to use each configuration【/cache/repos/github.com/every-app/open-seo/main/docs/LOCAL_DEVELOPMENT.md#L58-L66】.

## Key Configuration Files

Understanding these files helps troubleshoot and extend your local environment:

- **[`docs/LOCAL_DEVELOPMENT.md`](https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md)** – Contains the complete official documentation for prerequisites, database setup, and server commands.
- **[`package.json`](https://github.com/every-app/open-seo/blob/main/package.json)** – Defines all npm scripts including `dev`, `dev:agents`, and `db:migrate:local`.
- **`.env.example`** – Template showing required environment variables, particularly `DATAFORSEO_API_KEY`.
- **[`vite.config.ts`](https://github.com/every-app/open-seo/blob/main/vite.config.ts)** – Configures the Vite development server, including proxy settings for portless integration.

## Summary

- **Install prerequisites**: Node 20+ and pnpm 10 are required before cloning the every-app/open-seo repository.
- **Initialize the database**: Run `pnpm run db:migrate:local` once to apply D1-style migrations to the local SQLite database.
- **Configure environment**: Copy `.env.example` to `.env.local` and set `DATAFORSEO_API_KEY` as a Base64-encoded string.
- **Start the server**: Use `pnpm run dev` for standard mode or `pnpm dev:agents` for stable hostnames with logging.
- **Manage auth**: Default mode bypasses authentication; set `AUTH_MODE=cloudflare_access` to test access controls.

## Frequently Asked Questions

### What Node.js version is required for OpenSEO development?

OpenSEO requires **Node.js 20 or higher**. The project uses modern JavaScript features and the Vite build tool, which depend on recent Node APIs. Install pnpm globally with `npm i -g pnpm@10` before running `pnpm install`.

### How do I encode my DataForSEO credentials for the environment file?

DataForSEO credentials must be Base64-encoded in the format `login:password`. Use the command `printf '%s' 'mylogin:mypassword' | base64` in your terminal to generate the encoded string, then paste the result into `.env.local` as `DATAFORSEO_API_KEY=encoded_value`.

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

`pnpm run dev` starts a standard Vite development server, while `pnpm dev:agents` uses **portless** to create a stable hostname (`open-seo.localhost:1355`) and logs output to `.logs/dev-server.log`. The agents mode is recommended for consistent local development and debugging.

### Can I test Cloudflare Access authentication locally?

Yes, though the default `AUTH_MODE=local_noauth` bypasses authentication. To test Cloudflare Access, start the server with `AUTH_MODE=cloudflare_access pnpm run dev` after configuring the appropriate access policies in your Cloudflare dashboard.