How to Customize the Audit Process in Open‑SEO: Configuration Options and Limits

You can customize the Open‑SEO audit process by adjusting two parameters in the AuditConfig object—maxPages to control crawl depth and lighthouseStrategy to toggle performance checks—while deeper crawling policies remain hard‑coded in the workflow modules.

The open‑source SEO toolkit every-app/open-seo exposes a server‑side audit workflow that allows limited but precise customization through configuration objects. While the core crawling logic is encapsulated in workflow phases, operators can tailor individual audit runs by modifying specific fields in the AuditConfig record stored with each audit.

Audit Configuration Options

Open‑SEO stores customizable parameters in the AuditConfig type defined in src/server/lib/audit/types.ts. When you invoke AuditService.startAudit, the function persists these values alongside the audit record, and downstream workflow phases read them to determine execution behavior.

Page Count Limits (maxPages)

The maxPages property defines the upper bound of URLs the crawler will visit during an audit. According to the source code in src/server/features/audit/services/AuditService.ts, this value is clamped against the AUDIT_LIMITS constant based on the user's plan tier—free plans default to 50 pages, while paid or self‑hosted deployments can specify higher limits or unlimited crawling.

Lighthouse Strategy (lighthouseStrategy)

The lighthouseStrategy field controls whether Google Lighthouse performance audits run against discovered pages. The enum accepts two values:

• "auto" – Executes Lighthouse on every page crawled
• "none" – Skips performance checks entirely

This setting is parsed in the workflow phases to conditionally launch the Lighthouse runner.

How the Audit Configuration Works

The audit lifecycle follows a strict persistence pattern. In AuditService.startAudit (lines 46‑69), the function constructs the audit record and embeds the supplied configuration as JSON. Later, retrieval methods such as getResults invoke parseAuditConfig (lines 70‑85) to deserialize these settings, while siteAuditWorkflowPhases.ts consumes the configuration to decide when to terminate crawling or skip performance analysis (lines 170‑176).

Because the workflow is implemented as a TanStack Server Function, these stored parameters represent the only runtime customization points available through the public API.

Starting an Audit with Custom Settings

To customize an audit, pass the configuration fields directly to the startAudit method:

import { AuditService } from "@/server/features/audit/services/AuditService";

await AuditService.startAudit({
  actorUserId: "user-123",
  billingCustomer: {
    userId: "user-123",
    userEmail: "user@example.com",
    organizationId: "org-456",
    projectId: "proj-789",
  },
  projectId: "proj-789",
  startUrl: "https://example.com",
  // Customizations:
  maxPages: 200,
  lighthouseStrategy: "none",
  limitTier: "self_hosted",
});

The maxPages: 200 value overrides the default crawl depth, while lighthouseStrategy: "none" disables performance audits. Note that maxPages remains subject to plan‑tier enforcement defined in AUDIT_LIMITS.

Retrieving Applied Configuration

Existing audits expose their stored configuration through the results endpoint:

import { AuditService } from "@/server/features/audit/services/AuditService";

const result = await AuditService.getResults("audit-uuid", "proj-789");
console.log(result.audit.config);
// Output: { maxPages: 200, lighthouseStrategy: "none" }

The getResults method uses parseAuditConfig to validate and return the JSON configuration persisted during audit creation.

Hard‑Coded Behaviors You Cannot Change

Not all aspects of the audit are configurable. The workflow phases in src/server/workflows/siteAuditWorkflowPhases.ts hard‑code policies for:

• URL discovery algorithms
• robots.txt handling
• Link‑following depth logic
• Request throttling and concurrency

Modifying these behaviors requires editing the workflow source code directly rather than passing configuration parameters.

Summary

• Open‑SEO audits are customized via the AuditConfig object stored with each audit record in src/server/lib/audit/types.ts.
• Two configurable fields exist: maxPages (crawl volume limit) and lighthouseStrategy (performance check toggle).
• Plan‑tier enforcement automatically clamps maxPages against AUDIT_LIMITS defined in AuditService.ts.
• Workflow internals such as crawling logic and robots handling are hard‑coded in siteAuditWorkflowPhases.ts and cannot be altered via configuration.

Frequently Asked Questions

Can I change the crawling speed or concurrent requests in Open‑SEO?

No. Concurrency, request throttling, and retry policies are hard‑coded in the workflow phases located in src/server/workflows/siteAuditWorkflowPhases.ts. To adjust crawling speed, you must modify the source code and redeploy the server.

What happens if I set maxPages higher than my plan allows?

The AuditService.startAudit function automatically clamps the supplied value against the AUDIT_LIMITS constant associated with your billing tier. For example, free plans are capped at 50 pages regardless of the maxPages value passed.

Does lighthouseStrategy: "none" improve audit speed?

Yes. Skipping Lighthouse checks eliminates the browser launch, page load, and performance calculation overhead for each URL. When set to "none", the workflow phases bypass the Lighthouse runner entirely, reducing total audit duration significantly.

Where is the audit configuration stored after creation?

The configuration is serialized as JSON and stored in the audit database record created by AuditService.startAudit (lines 46‑69). Subsequent workflow phases and the getResults method retrieve and parse this data using parseAuditConfig to determine runtime behavior.

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