Preview config

Use the preview section when reviewers need a live app alongside the transcript and diff. The shape can stay small for one service or expand to multiple services, infrastructure, secrets, and network policy.

143 supports two shapes:

• Single-service shorthand with top-level command, cwd, port, env, and ready.
• Multi-service config with primary and services.

Do not mix the two shapes in one config.

Repos may also wrap preview configs in a named config map:

{
  "preview": {
    "default": "web",
    "configs": {
      "web": { "name": "Web", "command": ["npm", "run", "dev"], "port": 3000, "credentials": { "mode": "none" }, "network": { "mode": "managed" } },
      "docs": { "name": "Docs", "command": ["npm", "run", "dev"], "port": 3001, "credentials": { "mode": "none" }, "network": { "mode": "managed" } }
    }
  }
}

Use preview.default to auto-select one config. If there are multiple configs and no default, callers must provide a preview config name.

Top-level fields

Install fields

Install caches are keyed from the install command, declared lockfiles, the platform sandbox cache ABI, and effective cache paths. They speed up preview startup without replacing source files from the session workspace. Routine 143 deploys do not change the ABI; platform operators bump it only when sandbox OS/toolchain/runtime compatibility changes.

Use preview.install for dependency installation only. Source-dependent builds belong in each service's build field. Normal starts and recycles run them against the current workspace; an exact-revision warm resume may reuse the completed build from its retained sandbox.

Inferred dependency cache paths:

Inference is relative to the dependency file directory. For example, services/api/poetry.lock infers services/api/.venv, and go.mod infers vendor.

Do not cache source directories, secret files, .git, .143/cache, .143/cache/preview-install, or any parent/glob path that can include preview install markers. requirements.txt is safe only when dependencies are pinned. For stale dependencies, change lockfiles or temporarily set cache.enabled: false.

Build-output cache

Build-output caches are separate from install outputs. They are restored after install and saved asynchronously after services report ready. JS lockfiles infer Turborepo cache directories; add other content-addressed caches, such as .next/cache, with preview.install.cache.build.paths.

Only cache build directories whose tool validates entries by content hash. A stale build cache should degrade to a partial miss, not serve wrong output.

Service fields

Constraints:

• At most 4 services per preview config.
• Ports must be unique.
• port must be in the range 1024 to 65535.
• ready.http_path must start with / and use safe URL path characters.

Infrastructure fields

Supported templates:

Supported inject_env placeholders are {{username}}, {{password}}, {{host}}, {{port}}, and {{database}}.

Secret bundle fields

New preview configs should prefer preview.secrets. The legacy preview.credentials shape remains supported for env-var-only credential sets.

preview.secrets may be a single object or an array of objects. The repo config never contains secret values. It only declares the bundle name, service scope, and expected output names. A bundle may deliver multiple environment variables and one generated file.

Admin-managed bundle outputs support:

For a whole JSON file such as development.conf.json, store the raw JSON document as the managed secret value and configure the file output as:

{
  "type": "file",
  "path": "development.conf.json",
  "format": "json",
  "value": "secret:development_conf_json"
}

Do not base64-encode JSON just to preserve quotes or newlines. 143 writes generated files as bytes and handles runtime shell transport internally.

Credential fields

Secret values do not belong in .143/config.json. Put public, non-secret values in service env; reference secrets with preview.secrets or legacy preview.credentials.

Network fields

Resource fields

Platform-injected environment

Every service receives:

Browser and verification policy

The optional preview.browser policy controls the session-owned browser:

• persist_session defaults to true.
• default_viewport defaults to 1440×900.
• allowed_paths defaults to ["/**"] and can narrow agent navigation within the preview origin.

The optional preview.verification policy reserves the settings used by the automatic verification coordinator. The coordinator is a later delivery phase; these settings do not yet trigger checks by themselves:

• auto defaults to true.
• max_attempts defaults to 3.
• timeout_seconds defaults to 300.
• viewports defaults to the browser viewport.
• smoke_paths defaults to the primary service readiness path.
• fail_on_console_error defaults to true.

These fields define bounded policy, not a test DSL. Keep complex deterministic workflows in repository Playwright tests.

Trust rules

Preview config is repository content. For fields that can expose secrets or network access, 143 reads from the base branch rather than an agent diff.

For non-connected previews, service runtime fields can come from the session diff. For connected previews, launch behavior is pinned to the base branch. A preview is connected when preview.secrets is present, preview.credentials.mode is not none, or preview.network.destinations is non-empty.

Runtime freshness

143 can live-update ordinary source changes through the preview's dev server. Dependency, preview config, build config, environment config, and schema changes require a preview refresh. Refreshes reuse install, package-manager, and build caches when their keys still match.

For task-based examples and behavior details, see Preview environments. For repo-wide setup, see Repo config.