How to Run OpenSEO in Local Development Without Authentication

Set the environment variable AUTH_MODE=local_noauth before starting the development server to bypass all authentication requirements and run OpenSEO as a single-admin local instance.

The every-app/open-seo repository ships with a specialized development mode that eliminates the need for Cloudflare Access or Better-Auth configuration during local testing. By activating local_noauth mode, developers can immediately access the full admin interface without credentials, streamlining the development workflow for UI features and API integrations.

Step-by-Step Local Setup

Configure the Environment Variable

The local_noauth mode is controlled through a single environment variable that the preflight checker evaluates at startup. According to src/lib/selfhost-preflight.ts, the system specifically checks for the string "local_noauth" to determine whether to bypass external authentication providers 【/src/lib/selfhost-preflight.ts†L50-L57】.

Set the variable in your shell before running any commands:

export AUTH_MODE=local_noauth

On Windows PowerShell:

$env:AUTH_MODE="local_noauth"

Start the Development Server

With the environment variable defined, launch the Vite-based development environment using the standard package script. The pnpm dev command reads the configuration from vite.config.ts and starts the UI and backend worker, typically available at http://localhost:5173.

AUTH_MODE=local_noauth pnpm dev

The same environment variable is referenced by the rank-tracking bootstrap script (scripts/seed-rank-tracking.ts) which automatically creates a default project for the local admin upon startup 【/scripts/seed-rank-tracking.ts†L20-L23】.

Verify Configuration (Optional)

Run the self-host preflight utility to confirm that your local environment is correctly configured for no-auth development:

pnpm ts-node scripts/selfhost-preflight.ts

With AUTH_MODE=local_noauth, this check validates that no external auth provider configuration is required and confirms the instance will operate as a single-admin deployment 【/src/lib/selfhost-preflight.ts†L50-L57】.

Seed Default Data (Optional)

To populate the local instance with a default organization, user, and project, execute the seeding scripts. The scripts/seed-projects.ts file bootstraps the local admin’s organization, user profile, and a “Default” project, mirroring what a real deployment would have 【/scripts/seed-projects.ts†L13-L15】.

AUTH_MODE=local_noauth pnpm ts-node scripts/seed-projects.ts

This step provides immediate data to explore the SEO dashboard features without manually creating resources.

Technical Implementation Details

Authentication Middleware Bypass

When AUTH_MODE=local_noauth is active, the authentication middleware implements a short-circuit that grants admin access automatically. In src/middleware/ensure-user/resolve.ts, the code checks the environment variable and immediately returns the local admin context, preventing redirects to Cloudflare Access or Better-Auth endpoints 【/src/middleware/ensure-user/resolve.ts†L15-L16】.

This bypass treats the entire deployment as a single-tenant instance owned by the default administrator, eliminating all login flows while preserving the admin permission structure.

Docker-Based Configuration

For containerized local development, include the AUTH_MODE variable in your Docker Compose configuration. The repository's README.md references the Docker self-host guide for this purpose 【/README.md†L48-L51】.

services:
  app:
    environment:
      - AUTH_MODE=local_noauth

The docs/SELF_HOSTING_DOCKER.md file contains complete instructions for containerized deployments using the local_noauth option.

Summary

• Set AUTH_MODE=local_noauth to disable authentication requirements in the every-app/open-seo codebase
• The src/lib/selfhost-preflight.ts file validates this mode during startup 【/src/lib/selfhost-preflight.ts†L50-L57】
• The development server starts normally with pnpm dev and serves the UI at http://localhost:5173
• src/middleware/ensure-user/resolve.ts handles the runtime authentication bypass 【/src/middleware/ensure-user/resolve.ts†L15-L16】
• Seeding scripts in scripts/seed-projects.ts create default data for immediate testing 【/scripts/seed-projects.ts†L13-L15】

Frequently Asked Questions

Is local_noauth mode safe for production deployments?

No. The local_noauth mode is designed exclusively for local development and testing. As implemented in src/middleware/ensure-user/resolve.ts, this mode grants unrestricted admin access to all requests without verification 【/src/middleware/ensure-user/resolve.ts†L15-L16】. Production environments must use Cloudflare Access or Better-Auth with secure AUTH_MODE configuration.

What user account gets created when I run the seed scripts?

The scripts/seed-projects.ts file creates a default local admin organization, user profile, and a "Default" project when executed with AUTH_MODE=local_noauth 【/scripts/seed-projects.ts†L13-L15】. This structure mirrors authenticated deployments but assigns ownership to the synthetic local admin account.

Can I switch from local_noauth to authenticated mode later?

Yes. Simply unset or change the AUTH_MODE environment variable and restart the server. The application reads this configuration at startup in src/lib/selfhost-preflight.ts 【/src/lib/selfhost-preflight.ts†L50-L57】. However, you must configure proper Cloudflare Access or Better-Auth credentials before restarting, as the system will enforce authentication once the bypass is disabled.

Which source files control the local_noauth behavior?

The primary logic resides in two locations: src/lib/selfhost-preflight.ts handles the initial environment validation 【/src/lib/selfhost-preflight.ts†L50-L57】, while src/middleware/ensure-user/resolve.ts implements the runtime authentication bypass 【/src/middleware/ensure-user/resolve.ts†L15-L16】. The seeding utilities in scripts/seed-projects.ts and scripts/seed-rank-tracking.ts provide the data layer support for this mode 【/scripts/seed-projects.ts†L13-L15】 【/scripts/seed-rank-tracking.ts†L20-L23】.

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