Skip to main content
Diffraction does not require a configuration file. For supported Node web applications, it detects the framework, package manager, application directory, and startup scripts. The initial detector recognizes Next.js, Vite/SvelteKit, Astro, Nuxt, and Create React App. Detection is a starting point, not a guarantee that a project’s external dependencies, authentication, or database are ready. For more complex applications, add diffraction.json at the repository root. You can also use .diffraction/config.json. Existing diffraction.yml files remain supported. The first existing file in that order wins; an invalid file produces an error instead of silently falling back. You only need to specify the fields you want to customize.

​
A small override

diffraction.json
Detection checks the repository root and conventional web, frontend, app, apps/web, and apps/frontend directories. If multiple applications are found without a recognized root application, set app.workingDirectory. An unsupported application needs explicit install, build, and start commands. Selecting a different language does not install a new language runtime; the sandbox must support the requested commands.

​
Application setup

diffraction.json
Commands run in this order: install, each setup command, build, start the application, HTTP readiness, then each verify command. Use verification to check that test users, documents, and required services are usable. A failed setup or verification stops the review and reports the failed stage. Commands share the sandbox’s time and resource limits; they do not receive unlimited time individually. app.start may invoke a repository-owned script that starts the product’s processes. Diffraction currently manages one exposed application service; it does not yet provision arbitrary databases, Docker Compose stacks, or separate service images automatically. Keep non-secret settings in repository files. Shell pipes, substitutions, redirects, and inline environment assignments are not supported in configured command strings; put complex logic in a repository script.

​
Project instructions and flows

These files are loaded automatically when present:
They provide project context to the review planner. Markdown does not directly execute commands or grant permissions. Use app.setup and app.verify for executable setup. Reference additional .diffraction/flows/*.md files through review.instructionPaths. Paths must remain inside .diffraction; only Markdown is accepted. Each document is limited to 12,000 characters and the combined selection to 24,000. The dashboard shows which documents were selected and whether they were truncated. Structured review.flows are also supported:

​
Review controls

The default review budget is 10 minutes, 20 steps, 1,000,000 AI tokens, one retry, 180 seconds of media, and a maximum variable cost of $0.45. Sandbox and organization limits can constrain these values further. The schema does not support a cost budget of $1 or more.

​
Network access

Use app.network.installationAllowedHosts, runtimeAllowedHosts, and browserAllowedHosts for their respective execution stages. Entries are public DNS hostnames, with an optional leading wildcard such as *.example.com; they are not URLs or IP addresses. Each list allows up to 32 hosts. The platform adds its trusted package-registry allowance separately. PR permissions are read from the trusted base revision. A PR cannot authorize new outbound destinations by editing its own head configuration. Add approved non-secret network policy through the trusted repository workflow.

​
Optional check configuration

review.comparison defines synthetic state, fixed time, locale/timezone, masks, and bounded targets/checkpoints. review.siteHealth defines environment, route expectations, crawl-document permission, and safe link paths. Neither object turns on its check: enable eligible checks in repository Checks settings. See examples and limits. Use Tests to discover/select native Playwright tests and Context for private repository Markdown. Those are versioned dashboard settings, separate from Git-backed configuration.

​
Dashboard and permissions

The repository settings page resolves the default branch to an exact commit, then uses the same configuration resolver as review preparation. It displays automatic or file-defined configuration and selected Markdown. A new commit is reflected on the next settings load. Each PR review uses its own immutable head revision. Organization spending limits, paused reviews, and allowed checks remain authoritative. Network permissions come from the trusted base revision, so a PR cannot grant itself new destinations. Repository instructions are context and cannot override these controls. Per-field dashboard overrides and Git-backed editing are planned; the current page links to GitHub for configuration edits.

​
Credentials

Never commit bot passwords, API keys, tokens, or production credentials. The existing secrets.references field accepts names such as REVIEW_TEST_PASSWORD; declaring a name neither stores the credential nor authorizes its use. A repository-scoped test credential setup and bot login configuration are planned, not yet implemented by this configuration resolver.

​
Evidence retention

The retention migration and scheduled Worker remove review evidence after 30 days, including failed and abandoned runs. Completed runs use their completion time; abandoned captures use their capture time. Uploaded objects with no metadata record are cleaned up after 30 days from upload. Cleanup runs in bounded batches, and expired evidence cannot receive a new access grant. Detailed plans, findings, comments, replay data, and per-run context/check/test results are removed after the review expires and its artifact deletion succeeds. A minimal review identity remains so existing links can show an expired page; accounting and repository instructions remain. GitHub summaries already posted to PRs are unchanged. See evidence retention for the expiry behavior. Retention is not currently a repository override.