Project configuration

All worktrees use the primary checkout's .redpact/settings.json. The selected execution checkout supplies Compose files, Dockerfiles, application source and tests. Sharing configuration does not share execution resources: each run creates and removes its own application containers, dependency containers and network.

Use redpact settings describe --scope project --path /absolute/checkout for the generated schema and settings get for the authored values and revision. Apply changes through settings patch, then settings validate with the same scope and path. Agents do not read or edit project or instance JSON files directly. The shared files remain the storage format; see settings ownership for partial updates and repair. Validation returns the fixed plan without starting anything or proving readiness or approval.

Fixed execution plan

{
  "composeFiles": ["compose.yaml"],
  "services": ["app"],
  "dependencies": {
    "database": { "kind": "isolated", "services": ["db"] },
    "payments": {
      "kind": "mock",
      "services": ["payments"],
      "env": { "app": { "PAYMENTS_URL": "http://payments:8080" } }
    },
    "search": {
      "kind": "shared-local",
      "env": { "app": { "SEARCH_URL": "http://host.docker.internal:9200" } }
    },
    "provider": {
      "kind": "remote",
      "env": { "app": { "API_KEY": "replace-with-your-local-value" } }
    }
  },
  "tests": {
    "directory": "integration",
    "env": { "APP_URL": "http://app.redpact.test:3000" }
  }
}

The example requires actual Compose services and reachable existing endpoints. A mock declaration does not implement a substitute. services declares fixed roots; managed dependency services and Compose prerequisites complete the plan. Application metadata and relationships describe topology without activating extra services.

Each dependency has exactly one kind: isolated, mock, shared-local or remote. Isolated dependencies require services. Mock dependencies use implemented application behavior, managed services, or both. External connections cannot declare services and are never started or removed by Redpact. Shared services need fixture isolation for concurrent executions.

Compose remains the execution definition; settings validation does not impose a restricted Compose subset. See Compose and source capture for ownership, runtime input capture and native startup error handling.

Environment and connections

Dependency env is keyed by destination Compose service and variable. Strings override values; omission preserves defaults; { "unset": true } removes a variable. Conflicting writes from two dependencies fail even if their values are equal. Environment bindings do not start their target service.

tests.env is the common Integration and Playwright runner environment. Declare only runner variables that tests need; application variables are not copied. All values are plain strings. There is no secret, host, port or URL value type, reference lookup or server-environment fallback. Write URLs and ports as strings yourself, for example "APP_URL": "http://app.redpact.test:3000". Managed services have <service>.redpact.test DNS aliases on the execution network; host published ports remain separate inspection endpoints.

Supply values through CLI settings patches, or use Dependencies for application values and Project settings for tests.env. Both editors use key and value fields. There is no separate credential store, input card or API. Empty strings, whitespace, = and $ are literal; JSON \n represents a newline. There is no dotenv parser, shell expansion or automatic .env discovery.

Every nonempty application/test value is masked in execution text, including application shutdown logs. Browser runs with any such value omit traces. Values are matched literally, longest first; short values can mask ordinary log text too. Accepted execution settings fix values for that execution; later edits affect future runs only.

Values remain plaintext in settings, their read APIs and captured configuration or source. Masking is not encryption and does not sanitize these records, screenshots or video. Keep sensitive settings out of Git/public exports.

Inside a container, localhost is that container. A host-local service must be reachable from the runner and application that consume it. Merely changing an address does not prove connectivity; loopback-only host services require an accessible connection path. Remote endpoints retain their real origins, TLS and authentication. Browser-to-API access must also satisfy the application's CORS and cookie rules.

Runner declarations

tests.directory defaults to integration; tests.timeoutMs defaults to 10000. The timeout accepts integers from 1 to 2147483647 milliseconds (Node's timer limit), including 180000 for three minutes. It supplies Vitest's default test and hook timeout; explicit test/hook timeouts can override that default. It does not cover container preparation or change the separate instance execution budget. See limits and verdicts. Unit uses its existing unitTests Dockerfile, complete command, cwd and patterns. Playwright requires an application service, port and named targets with purpose functional or capture, and scope project or worktree. Browser language is playwright.locale; scenario UI language is playwright.uiLanguage, supplied as REDPACT_UI_LANGUAGE. See execution for execution and cleanup.

Settings are strict JSON with normalized project-relative paths, no duplicate or unknown keys, imports or format selector. Empty settings support inspection. Managed application execution requires configured roots and Compose services.

Incompatible settings change

Secret references and typed service endpoints are also retired. Replace them in authored settings with explicit string values. Historical runtime records use the ordered storage migration; project settings are never rewritten automatically.

Mode catalogs, execution-time selection, integration default files and worktree dependency overlays are retired. Update existing settings through CLI patches with fixed roots and dependency definitions. There are no backward readers or automatic migrations. The old selection and overlay files do not affect the plan. See settings ownership for file ownership and captured inputs.

Instance settings

Global Settings and redpact settings describe|get|patch|validate --scope instance control the instance separately. Instance projects lists absolute directories to observe. server.port applies after restart. Optional github.cliPath selects an absolute GitHub CLI executable.

Per-execution limits belong in instance settings:

{
  "testResources": {
    "memoryMiB": 2048,
    "timeoutSeconds": 600
  }
}

These omitted defaults apply to subsequent managed unit, integration, and Playwright executions. Memory allows 64–1048576 MiB; time allows 1–86400 seconds. They are separate from per-test timeouts and do not limit application containers, builds, or direct shell test commands. See resource coverage.

Main manual dependency host ports

A managed dependency can declare hostPorts, for example "hostPorts": [{ "service": "langfuse", "target": 3000, "published": 33181 }]. The service must belong to that dependency and publish the target TCP port in Compose. Ports are integers from 1 to 65535; duplicate targets or host ports are invalid. Only a manual environment on the configured main checkout uses these fixed host ports. Feature worktrees and all test environments use automatic publications, as do services without a fixed declaration. Compose-authored host port numbers are replaced by this policy. Actual Docker bindings supply inspection endpoints. An occupied fixed port fails with its service/port and remediation; Redpact never silently chooses a fallback.

Local clients can keep endpoint URLs and credentials in their own Git-ignored .env or environment variables, including a separate external Langfuse. Redpact does not read those client files or migrate existing dependency data. shared-local and remote dependencies cannot declare managed host ports.

Default execution scope

tests.executionScope is the shared default for Unit, Integration and Playwright, not just Integration. It accepts all (the omitted default) or changed. Agent API/CLI execution requests can override it with executionScope. The viewer's Run controls use this shared default and have no per-run Execution scope selector. Catalog filters and Playwright target maintenance scope remain separate. Recorded approval/result evidence still shows requested and resolved scope; see selection rules.

Unit commands retain their existing behavior when unitTests.fileCommand is absent: all runs command unchanged, with no claim about its discovered file list. changed requires the explicit file-command contract below and rejects an arbitrary shell command. The file-command catalog currently requires a Git checkout in both scopes; a directory-only project can retain its legacy all command. Opting into fileCommand makes both scopes run its executable and arguments followed by exact absolute /workspace/... test paths, with unitTests.cwd as the working directory. The executable must accept trailing file arguments and run exactly those files. This is an authored runner contract, not command-string inspection. Use a runner such as Vitest that supports file filters; avoid scripts that discard arguments or independently run other suites. Arguments and filenames are passed literally, never interpolated into shell code.

{
  "tests": { "executionScope": "all", "env": {} },
  "unitTests": {
    "dockerfile": "unit.Dockerfile",
    "cwd": "app/server",
    "command": "pnpm test",
    "patterns": ["app/server/test/*.test.ts"],
    "fileCommand": { "executable": "pnpm", "args": ["exec", "vitest", "run", "--"] }
  }
}

Install/build prerequisites in the Unit image; fileCommand replaces command for an opted-in execution and does not run its shell preparation steps first.

Configure the Git output bound with the server environment variable REDPACT_GIT_MAX_BUFFER_MIB (default 128 MiB). See Git query limits for range, restart and coverage. This is not an instance JSON field.