### Quickstart Docker Setup

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md

Copy the example environment file and start the OpenSEO service in detached mode. Ensure DATAFORSEO_API_KEY is set in the .env file.

```bash
cp .env.example .env
docker compose up -d
```

--------------------------------

### Start Development Server (Basic)

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md

Starts the local development server with default settings. This is a basic option for running the application locally.

```sh
pnpm run dev
```

--------------------------------

### Install All OpenSEO Skills

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/skills/setup.md

Use this command to install every available OpenSEO skill for your agent.

```bash
npx skills add every-app/open-seo --skill '*'
```

--------------------------------

### Start Development Server with Logging

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md

Starts the local development server and directs logs to a fixed file (.logs/dev-server.log). This is recommended for easier debugging, especially when using coding agents.

```sh
mkdir .logs
touch .logs/dev-server.log
pnpm dev:agents
```

--------------------------------

### Install Dependencies

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md

Installs project dependencies using pnpm. Ensure Node.js 20+ and pnpm are installed.

```sh
pnpm install
```

--------------------------------

### Install All OpenSEO Skills for OpenAI Codex Agent

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/skills/setup.md

Use this command to install every OpenSEO skill, but only make them available for the OpenAI Codex agent.

```bash
npx skills add every-app/open-seo --skill '*' --agent codex
```

--------------------------------

### Install OpenSEO Skills Interactively

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/skills/setup.md

Use this command to add OpenSEO skills and be prompted to choose available skills and agents interactively.

```bash
npx skills add every-app/open-seo
```

--------------------------------

### Install All OpenSEO Skills for Claude Code Agent

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/skills/setup.md

Use this command to install every OpenSEO skill, but only make them available for the Claude Code agent.

```bash
npx skills add every-app/open-seo --skill '*' --agent claude-code
```

--------------------------------

### Manually Copy OpenSEO Skill Files

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/skills/setup.md

Clone the OpenSEO repository and manually copy the skill files into the appropriate agent directories if you prefer manual installation.

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

# Codex
mkdir -p ~/.codex/skills
cp -R open-seo/.agents/skills/* ~/.codex/skills/

# Claude Code
mkdir -p ~/.claude/skills
cp -R open-seo/.agents/skills/* ~/.claude/skills/
```

--------------------------------

### Clone OpenSEO Repository

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md

Clone the OpenSEO repository locally and install dependencies. Use the upstream repo if a fork is not needed.

```bash
git clone https://github.com/YOUR_GITHUB_USER/open-seo.git
cd open-seo
corepack enable
pnpm install
```

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

--------------------------------

### Generate Release Notes with Specific Tags

Source: https://github.com/every-app/open-seo/blob/main/docs/MAINTAINERS.md

Generate release notes between specific tags or to HEAD. The `--from` flag specifies the starting tag, and `--to` specifies the ending reference.

```sh
pnpm release:notes -- --from v0.0.1 --to HEAD
```

--------------------------------

### Migrate Local Database

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md

Applies database migrations for the local development environment. Run this once after a fresh local database setup.

```sh
pnpm run db:migrate:local
```

--------------------------------

### Onboarding Seed Function Logic

Source: https://github.com/every-app/open-seo/blob/main/specs/0006-onboarding-agent-implementation.md

This outlines the steps involved in the runOnboardingSeed function, from admission marking to persisting the results. It details the atomic update for the admission marker and the sequential scraping of key pages.

```sql
UPDATE projects SET onboarding_run_status = 'running' WHERE id = ? AND onboarding_run_status IS NULL
```

--------------------------------

### runOnboardingSeed Function

Source: https://github.com/every-app/open-seo/blob/main/specs/0006-onboarding-agent-implementation.md

Initiates the onboarding process for a project, including discovery, reading, signaling, synthesizing, and persisting data.

```APIDOC
## runOnboardingSeed

### Description
Initiates the onboarding process for a project. This function performs several steps including:
1. Setting an admission marker to ensure at-most-once execution.
2. Discovering robots.txt and sitemap.xml.
3. Reading and scraping key pages to markdown.
4. Signaling by fetching project overview and performing keyword research.
5. Synthesizing a strategy markdown using AI.
6. Persisting the results and updating the onboarding run status.

### Parameters
- **projectId** (string) - The ID of the project.
- **organizationId** (string) - The ID of the organization.
- **userId** (string) - The ID of the user.
- **userEmail** (string) - The email of the user.
- **domain** (string) - The domain for the onboarding process.
```

--------------------------------

### Preview Local Docker/SQLite Default Project Cleanup

Source: https://github.com/every-app/open-seo/blob/main/docs/default-project-cleanup.md

Preview the default project cleanup process when using a local Docker or SQLite-backed D1 database.

```sh
pnpm cleanup:default-projects:d1 --database open-seo --local
```

--------------------------------

### Add Upstream Git Remote

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md

Run this command once in your local repository to add the official OpenSEO repository as a remote named 'upstream'. This is part of the one-time setup for updating.

```bash
git remote add upstream https://github.com/every-app/open-seo.git
git fetch upstream
```

--------------------------------

### Preview D1 Default Project Cleanup

Source: https://github.com/every-app/open-seo/blob/main/docs/default-project-cleanup.md

Preview the default project cleanup process for a D1 database. Use this to verify changes before applying them.

```sh
pnpm cleanup:default-projects:d1 --database open-seo
```

--------------------------------

### Pull Latest Image and Restart

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md

Update the OpenSEO service to the latest published Docker image and restart it.

```bash
docker compose pull && docker compose up -d
```

--------------------------------

### Onboarding Chat API

Source: https://github.com/every-app/open-seo/blob/main/specs/0006-onboarding-agent-implementation.md

Provides a chat interface for interacting with the onboarding agent, allowing users to update project context.

```APIDOC
## POST /api/onboarding/chat

### Description
Handles chat interactions for the onboarding process. It uses an AI model to generate responses and allows for updating project context.

### Method
POST

### Endpoint
/api/onboarding/chat

### Authentication
Requires authentication via a resolved 'better-auth' session. Asserts that the user owns the specified `projectId`.

### Request Body
(Implicitly handled by TanStack createFileRoute and AI SDK)

### Response
Streams AI-generated messages, including context updates.

### Related Client SDK
AI SDK `useChat({ api: '/api/onboarding/chat' })`
```

--------------------------------

### Build and Run Local Docker Image

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md

For testing local code changes, build a custom Docker image using the Dockerfile.selfhost and then run it by setting OPEN_SEO_IMAGE to your local tag.

```bash
docker build -f Dockerfile.selfhost -t open-seo:local .
OPEN_SEO_IMAGE=open-seo:local docker compose up -d
```

--------------------------------

### Create Cloudflare Resources with Wrangler

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md

Provision necessary Cloudflare resources like KV namespaces, D1 databases, and R2 buckets. Ensure unique names by replacing YOUR_SUFFIX.

```bash
pnpm exec wrangler kv namespace create open-seo-YOUR_SUFFIX
pnpm exec wrangler kv namespace create open-seo-oauth-YOUR_SUFFIX
pnpm exec wrangler d1 create open-seo-YOUR_SUFFIX
pnpm exec wrangler r2 bucket create open-seo-YOUR_SUFFIX
```

--------------------------------

### Apply D1 Default Project Cleanup

Source: https://github.com/every-app/open-seo/blob/main/docs/default-project-cleanup.md

Apply the default project cleanup to a D1 database after previewing. Requires confirmation for remote apply.

```sh
pnpm cleanup:default-projects:d1 --database open-seo --apply --confirm-remote-apply
```

--------------------------------

### Apply Local Docker/SQLite Default Project Cleanup

Source: https://github.com/every-app/open-seo/blob/main/docs/default-project-cleanup.md

Apply the default project cleanup to a local Docker or SQLite-backed D1 database after previewing.

```sh
pnpm cleanup:default-projects:d1 --database open-seo --local --apply
```

--------------------------------

### Recommended Release Flow

Source: https://github.com/every-app/open-seo/blob/main/docs/MAINTAINERS.md

A recommended workflow for releasing OpenSEO, involving generating notes, manually editing them, and then creating a GitHub release.

```sh
pnpm -s release:notes
# edit and save the final copy in release-notes/v0.0.2.md
gh release create v0.0.2 --target main --title v0.0.2 --notes-file release-notes/v0.0.2.md
```

--------------------------------

### Add OpenSEO MCP Server for Claude

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md

Use this command to add the OpenSEO MCP server for Claude. The `--scope user` flag makes OpenSEO available across projects, while `--scope local` is for the current repository.

```bash
claude mcp add --transport http --scope user openseo https://app.openseo.so/mcp
```

--------------------------------

### View Docker Compose Configuration

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md

Inspect the effective Docker Compose configuration, including environment variables, to troubleshoot issues.

```bash
docker compose config
```

--------------------------------

### Client-side Chat Hook

Source: https://github.com/every-app/open-seo/blob/main/specs/0006-onboarding-agent-implementation.md

This shows how to use the AI SDK's useChat hook on the client-side to interact with the onboarding chat API. The strategy renders above the chat, and an upgrade CTA is shown once v1 exists.

```javascript
useChat({ api: '/api/onboarding/chat' })
```

--------------------------------

### OpenCode Slash Command for Release Notes

Source: https://github.com/every-app/open-seo/blob/main/docs/MAINTAINERS.md

A convenience command for use within OpenCode to trigger the release notes generator. It forwards any additional arguments to the generator script.

```text
/release-notes
```

--------------------------------

### Onboarding Chat API Handler

Source: https://github.com/every-app/open-seo/blob/main/specs/0006-onboarding-agent-implementation.md

This describes the server-side handler for the onboarding chat API using TanStack createFileRoute. It details authentication, the use of streamText for AI responses, and the update_project_context function for persisting changes.

```typescript
streamText({ model: openrouter(MODEL), system: seededWithContext, messages, tools: { update_project_context } })
```

```typescript
update_project_context({ markdown, note })
```

--------------------------------

### Create Draft GitHub Release

Source: https://github.com/every-app/open-seo/blob/main/docs/MAINTAINERS.md

Generate release notes and create a draft GitHub release for a specified tag. This command uses the `--draft` flag to initiate the draft creation process.

```sh
pnpm release:notes -- --draft v0.0.2
```

--------------------------------

### Update OpenSEO to Latest Version

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md

These commands should be run every time you update the OpenSEO project. They fetch the latest changes from the upstream repository, back up your local configuration, reset your local main branch to match the upstream, restore your local configuration, and then commit and push the changes.

```bash
git fetch upstream
cp wrangler.jsonc wrangler.local.backup.jsonc
git checkout main
git reset --hard upstream/main
cp wrangler.local.backup.jsonc wrangler.jsonc
git add wrangler.jsonc
git commit -m "restore Cloudflare settings" || true
git push --force-with-lease origin main
```

--------------------------------

### Configure MCP Server in Cursor

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md

Add the OpenSEO MCP server configuration to your Cursor `mcp.json` file. This allows Cursor to connect to the OpenSEO MCP service.

```json
{
  "mcpServers": {
    "openseo": {
      "url": "https://app.openseo.so/mcp"
    }
  }
}
```

--------------------------------

### Log in to Cloudflare with Wrangler

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md

Authenticate with Cloudflare using the Wrangler CLI.

```bash
pnpm exec wrangler login
```

--------------------------------

### Deploy OpenSEO Worker with Wrangler

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md

Deploy the OpenSEO application using Wrangler after configuring `wrangler.jsonc`.

```bash
pnpm run deploy
```