---
sidebar_position: 3.5
id: "presets"
title: "Presets"
---

# Presets

Wave's preset system allows you to save and apply multiple configuration settings at once. Presets can be used in two different scenarios:

- AI models: Configure different AI providers and models (see [AI Presets](/ai-presets))
- Tab backgrounds: Apply visual styles to your tabs

## Managing Presets

You can store presets in two locations:

- `~/.config/waveterm/presets.json`: Main presets file
- `~/.config/waveterm/presets/`: Directory for organizing presets into separate files

All presets are aggregated regardless of which file they're in, so you can use the `presets` directory to organize them (e.g., `presets/bg.json`, `presets/ai.json`).

:::info
You can easily edit your presets using the built-in editor:

```bash
wsh editconfig presets.json        # Edit main presets file
wsh editconfig presets/ai.json     # Edit AI presets
```

:::

## File Format

Presets follow this format:

```json
{
  "<preset-type>@<preset-key>": {
    "display:name": "<Preset name>",
    "display:order": "<number>", // optional
    "<overridden-config-key-1>": "<overridden-config-value-1>"
    ...
  }
}
```

The `preset-type` determines where the preset appears in Wave's interface:

- `ai`: Appears in the models dropdown in the "Wave AI" widget header (see [AI Presets](/ai-presets))
- `bg`: Appears in the "Backgrounds" submenu when right-clicking a tab

### Common Keys

| Key Name      | Type   | Function                                  |
| ------------- | ------ | ----------------------------------------- |
| display:name  | string | Name shown in the UI menu (required)      |
| display:order | float  | Controls the order in the menu (optional) |

:::info
When a preset is applied, it overrides the default configuration values for that tab or block. Using `bg:*` or `ai:*` will clear any previously overridden values, setting them back to defaults. It's recommended to include these keys in your presets to ensure a clean slate.
:::

## AI Presets

For configuring AI providers and models, see our dedicated [AI Presets](/ai-presets) documentation. It covers setting up presets for:

- Local LLMs via Ollama
- Azure OpenAI
- Anthropic's Claude
- Perplexity
- And more

## Background Presets

Wave's background system harnesses the full power of CSS backgrounds, letting you create rich visual effects through the "background" attribute. You can apply solid colors, gradients (both linear and radial), images, and even blend multiple elements together.

### Configuration Keys

| Key Name             | Type   | Function                                                                                                |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| bg:\*                | bool   | Reset all existing bg keys (recommended to prevent any existing background settings from carrying over) |
| bg                   | string | CSS `background` attribute for the tab (supports colors, gradients images, etc.)                        |
| bg:opacity           | float  | The opacity of the background (defaults to 0.5)                                                         |
| bg:blendmode         | string | The [blend mode](https://developer.mozilla.org/en-US/docs/Web/CSS/blend-mode) of the background         |
| bg:bordercolor       | string | The color of the border when a block is not active (rarely used)                                        |
| bg:activebordercolor | string | The color of the border when a block is active                                                          |

### Examples

#### Simple solid color:

```json
{
  "bg@blue": {
    "display:name": "Blue",
    "bg:*": true,
    "bg": "blue",
    "bg:opacity": 0.3,
    "bg:activebordercolor": "rgba(0, 0, 255, 1.0)"
  }
}
```

#### Complex gradient:

```json
{
  "bg@duskhorizon": {
    "display:name": "Dusk Horizon",
    "bg:*": true,
    "bg": "linear-gradient(0deg, rgba(128,0,0,1) 0%, rgba(204,85,0,0.7) 20%, rgba(255,140,0,0.6) 45%, rgba(160,90,160,0.5) 65%, rgba(60,60,120,1) 100%), radial-gradient(circle at 30% 30%, rgba(255,255,255,0.1), transparent 60%), radial-gradient(circle at 70% 70%, rgba(255,255,255,0.05), transparent 70%)",
    "bg:opacity": 0.9,
    "bg:blendmode": "overlay"
  }
}
```

#### Background image:

```json
{
  "bg@ocean": {
    "display:name": "Ocean Scene",
    "bg:*": true,
    "bg": "url('/path/to/ocean.jpg') center/cover no-repeat",
    "bg:opacity": 0.2
  }
}
```

:::info
Background images support both URLs and local file paths. For better reliability, we recommend using local files. Local paths must be absolute or start with `~` (e.g., `~/Downloads/background.png`). We support common web formats: PNG, JPEG/JPG, WebP, GIF, and SVG.
:::

:::tip
The `setbg` command can help generate background preset JSON:

```bash
# Preview a solid color preset
wsh setbg --print "#ff0000"
{
  "bg:*": true,
  "bg": "#ff0000",
  "bg:opacity": 0.5
}

# Preview a centered image preset
wsh setbg --print --center --opacity 0.3 ~/logo.png
{
  "bg:*": true,
  "bg": "url('/absolute/path/to/logo.png') no-repeat center/auto",
  "bg:opacity": 0.3
}
```

Just add the required `display:name` field to complete your preset!
:::
