CLI Config Schema

Voyager config has two related but separate paths:

• Voyager CLI runtime loads and merges config locally.
• Cloud-served JSON Schema gives editors validation and completion for voyager.json and voyager.jsonc.

JSON Schema does not load, apply, or override runtime config.

{
  "$schema": "https://app.vgercode.com/config.json"
}

Two separate paths

flowchart LR
  subgraph runtime ["Runtime config loading"]
    files["Global, project, organization,<br/>managed, and runtime config sources"] --> loader["Voyager CLI config loader"] --> effective["Effective runtime config"]
  end

  subgraph schema ["Editor validation and completion"]
    info["Config.Info<br/>Effect Schema"] --> generated["Locally generated schema<br/>for verification"]
    upstream["https://voyagercode.ai/config.json"] --> overlay["Voyager Cloud merge route"]
    extras["Voyager extras.ts overlay buckets"] --> overlay --> endpoint["https://app.vgercode.com/config.json"] --> editor["Editor validation and completion"]
    generated -. "Keep aligned" .-> extras
  end

Changing runtime config precedence affects first path. Adding or changing config key affects both paths because editor schema must describe keys CLI accepts. See CLI Runtime config precedence for runtime merge order.

Source of truth

Canonical CLI config source is Effect Schema Config.Info in packages/voyagercode/src/config/config.ts in Voyager-Org/voyager. CLI derives .zod compatibility surface from Effect Schema for plugin and SDK consumers. Do not maintain separate handwritten Zod definition for Voyager config fields.

Cloud schema endpoint

Static source review of Voyager-Org/cloud shows this route behavior:

1. Editor fetches https://app.vgercode.com/config.json because config file references $schema.
2. Cloud route apps/web/src/app/config.json/route.ts fetches https://voyagercode.ai/config.json.
3. Route runs merge() and returns upstream schema with Voyager additions and overrides.
4. merge() overlays buckets from apps/web/src/app/config.json/extras.ts.

Cloud source defines 1-hour upstream revalidation and edge-cache headers. This describes checked-in route behavior, not live deployment or cache state.

Overlay buckets

Reviewed cloud source overlays:

Nested CLI fields outside these buckets need dedicated overlay bucket and matching merge() logic.

Failure mode

If cloud overlay misses valid CLI field, CLI can accept config while editor reports unknown property. Opposite drift is also possible: cloud schema can advertise field that runtime no longer accepts.

Treat schema synchronization as cross-repository contract. Tests should detect both missing valid fields and stale overlay entries. Keep branch-specific drift findings in tracked issues or test output, not this architecture page.

Adding or changing Voyager-only config key

1. Add or update Effect Schema field with voyager_change marker in packages/voyagercode/src/config/config.ts.
2. Generate JSON Schema shape:

bun --bun packages/voyagercode/script/schema.ts /tmp/voyager.json
jq '.properties.<new_key>' /tmp/voyager.json

3. Update matching bucket in apps/web/src/app/config.json/extras.ts in cloud repo.
4. Extend merge() in apps/web/src/app/config.json/route.ts when new nested bucket is required.
5. Add assertion in apps/web/src/tests/cli-config-schema.test.ts.
6. Audit stale overlay entries as well as missing additions.

Source map

Repository column identifies source root for each relative path.

Related pages

• CLI Runtime - runtime config loading and precedence
• Development Patterns - shared-file markers, Voyager-owned boundaries, and cross-repository contributor workflow