Override syntax

File types

Extension	Behavior
`.yaml` / `.yml`	Parsed as a patch and merged into the current profile.
`.js`	Runs `main(profile)`; its return value becomes the next profile.

Empty files are skipped with a warning. An unsupported extension fails configuration compilation.

YAML modifiers

Form	Behavior
`key: value`	Replaces scalars, merges objects recursively, and replaces plain lists.
`key-start: [...]`	Inserts items at the beginning of an existing list.
`key-end: [...]`	Appends items to an existing list.
`key-merge: {...}`	Recursively merges a map without removing existing keys.
`key-force: value`	Replaces the whole field without merging.
`<key-end>: value`	Treats a modifier-shaped field name literally.

Known lists such as rules, proxies, and proxy-groups support -start and -end. When named proxies or groups collide, the last definition wins.

rules-start:
  - DOMAIN-SUFFIX,lan,DIRECT

rules-end:
  - DOMAIN-SUFFIX,example.com,PROXY

hosts-merge:
  router.local: 192.168.1.1

dns-force:
  enable: true
  nameserver:
    - https://dns.alidns.com/dns-query

JavaScript

main(profile) may mutate and return profile, or return a new object. Returning undefined, an array, or a scalar makes that script fail; the previous profile is retained.

async function main(profile) {
  const response = await fetch("http://127.0.0.1:8080/rules.yaml");
  if (!response.ok) return profile;

  return deepMerge(profile, await response.yaml(), true);
}

`deepMerge`

JS form	Behavior
`key: value`	Replaces a scalar or list; merges objects recursively.
`"+key": [...]`	Inserts items at the beginning of a list.
`"key+": [...]`	Appends items to a list.
`"key!": {...}`	Replaces the target field with an object.
`"<key>": value`	Uses a literal field name.

Available APIs

API	Purpose
`yaml.parse(text)` / `yaml.stringify(value)`	Convert YAML and objects.
`deepMerge(target, patch, true)`	Merge objects with override semantics.
`fetch(url, init?)`	Make an HTTP request.
`response.text()` / `json()` / `yaml()`	Read a response body.
`console.log/info/warn/error/debug`	Write to the adjacent `.log` file.
`Buffer.from()`、`b64e()`、`b64d()`	Convert UTF-8 and Base64 values.

The embedded fetch supports http:// only, not HTTPS. Importing an override file from a URL supports both HTTP and HTTPS.

Failures

Situation	Result
YAML parsing fails	The profile compilation fails.
JavaScript throws or returns an invalid value	That script is skipped, the previous profile is retained, and a warning is logged.
An age-encrypted profile	Override warnings and JS logs redact profile content.

YumeBox then applies runtime constraints such as private provider paths, DNS defaults, and mode-specific patches. Enabling Disable all overrides in Root modes bypasses these runtime patches too.

Start here

App guide

Development

Override syntax

File types

YAML modifiers

JavaScript

`deepMerge`

Available APIs

Failures

​File types

​YAML modifiers

​JavaScript

​deepMerge

​Available APIs

​Failures

File types

YAML modifiers

JavaScript

`deepMerge`

Available APIs

Failures