# How to Run OpenSEO in Local Development Without Authentication

> Easily run OpenSEO in local development without authentication by setting the AUTH_MODE environment variable to local_noauth. Deploy your local instance quickly.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-09-10

---

**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`](https://github.com/every-app/open-seo/blob/main/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:

```bash
export AUTH_MODE=local_noauth

```

On Windows PowerShell:

```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`](https://github.com/every-app/open-seo/blob/main/vite.config.ts) and starts the UI and backend worker, typically available at `http://localhost:5173`.

```bash
AUTH_MODE=local_noauth pnpm dev

```

The same environment variable is referenced by the rank-tracking bootstrap script ([`scripts/seed-rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/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:

```bash
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`](https://github.com/every-app/open-seo/blob/main/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】.

```bash
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/README.md) references the Docker self-host guide for this purpose 【/README.md†L48-L51】.

```yaml
services:
  app:
    environment:
      - AUTH_MODE=local_noauth

```

The [`docs/SELF_HOSTING_DOCKER.md`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/lib/selfhost-preflight.ts) handles the initial environment validation 【/src/lib/selfhost-preflight.ts†L50-L57】, while [`src/middleware/ensure-user/resolve.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/scripts/seed-projects.ts) and [`scripts/seed-rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/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】.