<!-- Markdown mirror. Canonical: https://empryo.com/docs/reference/presets -->

# Presets

> Load shareable Empryo config bundles by name, path, or URL to sync task router, agent features, theme, and providers across machines and teams.

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:

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

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

```bash
# 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

```bash
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:

```bash
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:

```json
{
  "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). |

## See also

- [Configuration](/docs/reference/configuration) - the AppConfig shape presets layer onto.
- [Task router](/docs/recipes/task-router) - the most-changed slot in shared presets.