Presets are reusable config bundles - task router rules, agent features, theme, instruction files, custom providers - that merge into your AppConfig at boot. Useful for syncing settings across machines, sharing a team setup, or pinning a known-good config to a repo.

Three ways to load

Presets resolve in this order - later wins:

Global - ~/.empryo/config.json → presets[]
Project - <cwd>/.empryo/config.json → presets[]
CLI - --plugin <spec> (stackable) or EMPRYO_PRESETS=spec1,spec2

{
  "presets": [
    "team/standard",
    "./presets/local.json",
    "https://example.com/forge-preset.json"
  ]
}

# One-off CLI overlay (multiple --plugin flags stack)
empryo --plugin team/standard --plugin ./extra.json

# Same via env
EMPRYO_PRESETS=team/standard,./extra.json empryo

Spec formats

Form	Example
Registry id	`team/standard`
Absolute path	`/etc/forge/preset.json`
Relative path	`./presets/local.json`, `../shared.json`
Home path	`~/forge/preset.json`
URL	`https://example.com/preset.json`

Specs must be at least 2 characters and match ^(https?:\/\/|\.\/|\.\.\/|\/|~\/)|^[a-zA-Z0-9][a-zA-Z0-9._/-]{1,}$. Invalid specs are logged and skipped.

Wizard

empryo --presets
# or
empryo presets

Interactive picker - browse the registry, preview overlays, add to global or project scope.

Boot output

By default preset resolution is silent on success. Failures print one short line to stderr (one bad preset never blocks boot - fail-open). For full traces:

empryo --verbose-presets

You'll see one line per spec (ok or fail) with the resolved source.

How merging works

Presets are resolved to plain AppConfig patches, then merged on top of the built-in defaults in load order. The merged result is applied before your config is read, so every part of the app sees the same combined settings.

Your ~/.empryo/config.json is never rewritten. Removing the preset entry restores the prior behaviour on next launch.

Authoring

A preset is a JSON file (or registry-hosted JSON). It needs a name (lowercase, hyphenated) and a semver version; everything meaningful lives in config, which accepts any subset of AppConfig fields:

{
  "name": "team-standard",
  "version": "1.0.0",
  "description": "Team default router + theme + privacy",
  "config": {
    "theme": { "name": "catppuccin" },
    "taskRouter": {
      "spark": "anthropic/claude-haiku-4-5",
      "ember": "anthropic/claude-sonnet-4-5"
    },
    "agentFeatures": {
      "desloppify": true,
      "tierRouting": true
    },
    "forbiddenPatterns": ["*.env", "secrets/**"]
  }
}

Drop it under ~/.empryo/presets/<name>.json to make it discoverable, or host anywhere reachable by HTTPS.

Environment

Variable	Purpose
`EMPRYO_PRESETS`	Comma-separated specs (set automatically by `--plugin` flags).