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

# Presets

> Load shareable Empryo settings bundles by name, file path, or URL to keep your router, agent features, theme, and providers the same across machines and teams.

A preset is a JSON file of Empryo settings that you can share. Use one to give your whole team the same model routing, theme, and privacy rules, to keep your own machines in sync, or to pin a known-good setup to a repository.

Presets are applied on top of the built-in defaults when Empryo starts. They never rewrite your own config file. Remove a preset from the list and the next launch behaves as before.

## Load a preset

List presets in the `presets` array of a config file, or pass them on the command line.

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

```bash
# For one launch. Repeat --plugin to stack presets.
empryo --plugin team/standard --plugin ./extra.json

# The same, with an environment variable
EMPRYO_PRESETS=team/standard,./extra.json empryo
```

Empryo reads presets from three places. When two presets set the same thing, the later one wins:

1. **Global**: `presets` in `~/.empryo/config.json`
2. **Project**: `presets` in `.empryo/config.json` in your project
3. **Command line**: `--plugin <spec>` or `EMPRYO_PRESETS`

A project's presets only load after you [trust the repository](/docs/reference/configuration#privacy) with `/trust` or `--trust`, because a preset can start programs such as MCP servers.

## Ways to name a preset

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

URLs must use `https://`. Plain `http://` is refused, and so is a redirect to a non-HTTPS address. A registry name is looked up in Empryo's public preset registry. Anything that does not match one of these forms is skipped with a warning.

## Browse with the wizard

```bash
empryo presets
# or
empryo --presets
```

The wizard lets you browse the registry, preview what a preset changes, and add it to your global or project config.

## When a preset fails

Loading is quiet when everything works. If a preset fails, Empryo prints one short line and starts anyway. One broken preset never stops Empryo from launching.

To see what happened with each preset:

```bash
empryo --verbose-presets
```

This prints one line per preset, `ok` or `fail`, with where it was loaded from.

## Write a preset

A preset needs a `name` (lowercase letters, numbers, and hyphens) and a `version` in `x.y.z` form. Put the settings under `config`. It accepts any [configuration](/docs/reference/configuration) field.

```json
{
  "name": "team-standard",
  "version": "1.0.0",
  "description": "Team model routing, theme, and agent features",
  "config": {
    "theme": { "name": "catppuccin" },
    "taskRouter": {
      "spark": "anthropic/claude-haiku-4-5",
      "ember": "anthropic/claude-sonnet-4-5"
    },
    "agentFeatures": {
      "desloppify": true
    }
  }
}
```

Share it as a file in your repository, or host it at an HTTPS address. A preset file can be up to 512 KB.

## Environment

| Variable | What it does |
|----------|--------------|
| `EMPRYO_PRESETS` | Presets to load, separated by commas. `--plugin` sets this for you. |

## See also

- [Configuration](/docs/reference/configuration): every setting a preset can change.
- [Use multiple models](/docs/recipes/task-router): model routing, the setting teams share most often.