# Preset Configuration
A launcher preset is a stored record that defines how to launch an agent session. It selects a provider type, supplies provider-specific `config` defaults, declares environment variable indirections, and sets worktree policy. Presets are managed in **Settings > Agent Presets** and can be exported/imported as JSON.

## Full record shape

This is the complete preset shape as stored, exported, and imported:

```json
{
  "key": "coder-codex",
  "displayName": "Codex Coder",
  "providerType": "codex",
  "description": "Codex preset for coding tasks.",
  "tags": ["coding"],
  "allowAdhocOverrides": true,
  "config": {
    "model": "gpt-5.4",
    "keepAliveMs": 120000,
    "model_preferences": {
      "reasoning_effort": "medium"
    }
  },
  "env": [
    { "name": "CODEX_API_KEY", "valueRef": "CODEX_API_KEY" }
  ],
  "worktree": {
    "shouldCreateWorktree": true,
    "allowReuseExistingWorktree": false
  }
}
```

## Field reference

### Top-level fields

| Field | Type | Required | Purpose |
|-------|------|----------|---------|
| `key` | string | Yes | Unique preset key. Normalized to lowercase and trimmed. Max 160 characters. Immutable after creation. |
| `displayName` | string | Yes | Human-readable name shown in launcher dropdowns. Max 200 characters. |
| `providerType` | string | Yes | Must be a registered provider type: `claude`, `codex`, `gemini`, `openai`, `anthropic`, or `ollama`. |
| `description` | string \| null | No | Optional descriptive text. |
| `tags` | string[] | No | Freeform tags for grouping and filtering. Stored as trimmed non-empty strings. |
| `allowAdhocOverrides` | boolean | No | Whether users can override settings per-launch. Defaults to `true`. Currently a UI/operator policy flag. |

### `config` object

Arbitrary JSON. Keys are provider-specific — see [Provider Configuration](../overview/#per-provider-config-keys) for the full per-provider reference.

Two keys are cross-cutting and consumed by the launch framework before the provider sees the config:

| Key | Type | Consumed by | Notes |
|-----|------|-------------|-------|
| `keepAliveMs` | number | Launch framework | Extracted and forwarded separately. Session keep-alive timeout in ms. |
| `sessionIdleCloseMs` | number | Launch framework | Explicit idle-close delay. Currently only Codex uses it. |

All other keys are interpreted by the selected launcher according to its provider contract.

### `env` array

Environment variable references resolved at launch time. Values are read from your shell environment and are not embedded in the preset definition itself.

```json
"env": [
  { "name": "CODEX_API_KEY", "valueRef": "CODEX_API_KEY" }
]
```

| Field | Type | Purpose |
|-------|------|---------|
| `name` | string | Logical label for this env reference |
| `valueRef` | string | Environment variable name to read at launch time |

Set `"env": []` when the provider doesn't need API keys.

### `worktree` object

Controls git worktree behavior. These are consumed by the PM system before the provider launches — they're not passed as provider config.

| Field | Type | Default | Purpose |
|-------|------|---------|---------|
| `shouldCreateWorktree` | boolean | `true` | Create an isolated git worktree for each session |
| `allowReuseExistingWorktree` | boolean | `false` | Allow reuse of a worktree from a previous session on the same branch |

## Resolution behavior

When a session launches, the preset is resolved into a launchable configuration through these steps:

{{% steps %}}

### Resolve env sentinels

Preset `config` values can reference environment entries:

```json
{ "apiKey": "$env:CODEX_API_KEY" }
{ "baseUrl": { "envRef": "OPENAI_BASE_URL" } }
```

At resolution: `name` is looked up in preset `env` entries first, then the mapped `valueRef` is read from `process.env`. If the referenced variable is missing, resolution throws.

### Auto-inject API key

If resolved config doesn't contain `apiKey`, the matching provider setup's `apiKeyEnvVar` is used to inject one automatically. Resolution checks preset `env` entries first, then falls back to direct `process.env` lookup.

Treat raw session specs, screenshots, and exports as sensitive diagnostic data. Depending on the provider/runtime, resolved launch settings may include provider configuration derived at launch time.

### Merge launch overrides

Explicit `config` overrides from launch flows (e.g., `pm_session.launch_task`) merge on top of the resolved preset:

```
finalConfig = { ...resolvedPreset.config, ...launchOverrides.config }
```

This is a **shallow merge** — nested objects are replaced, not deep-merged.

### Apply provider remapping

For adapter providers, the default resolver injects the adapter selection:

| Requested `providerType` | Effective launcher | Injected config |
|--------------------------|-------------------|----------------|
| `claude` | Claude (native) | none |
| `codex` | Codex (native) | none |
| `gemini` | Gemini (native) | none |
| `openai` | TanStack | `adapter: "openai"` |
| `anthropic` | TanStack | `adapter: "anthropic"` |
| `ollama` | TanStack | `adapter: "ollama"` |

{{% /steps %}}

## Examples

### Claude — coding preset

```json
{
  "key": "coder-claude",
  "displayName": "Claude Coder",
  "providerType": "claude",
  "description": "Claude Code Coder",
  "tags": [],
  "allowAdhocOverrides": true,
  "config": {
    "model": "opus",
    "allowedTools": [],
    "keepAliveMs": 120000
  },
  "env": [],
  "worktree": {
    "shouldCreateWorktree": true,
    "allowReuseExistingWorktree": true
  }
}
```

### Codex — coding preset

```json
{
  "key": "coder-codex",
  "displayName": "Codex",
  "providerType": "codex",
  "description": "OpenAI Codex preset.",
  "tags": [],
  "allowAdhocOverrides": true,
  "config": {
    "model": "gpt-5.4",
    "keepAliveMs": 120000,
    "model_preferences": {
      "reasoning_effort": "medium"
    }
  },
  "env": [
    { "name": "CODEX_API_KEY", "valueRef": "CODEX_API_KEY" }
  ],
  "worktree": {
    "shouldCreateWorktree": true,
    "allowReuseExistingWorktree": false
  }
}
```

### Ollama — local orchestration preset

```json
{
  "key": "orchestrator-ollama",
  "displayName": "Ollama Local",
  "providerType": "ollama",
  "description": "Local Ollama preset.",
  "tags": [],
  "allowAdhocOverrides": true,
  "config": {
    "model": "qwen3-coder-next",
    "baseUrl": "http://localhost:11434",
    "temperature": 0.1,
    "maxOutputTokens": 4096,
    "keepAliveMs": 300000
  },
  "env": [],
  "worktree": {
    "shouldCreateWorktree": false,
    "allowReuseExistingWorktree": true
  }
}
```

## Import and export

Use **Export** and **Import** in Settings > Agent Presets. The export produces a JSON array of preset records.

Preset export/import can also be bundled with provider setups in a provider pack format:

```json
{
  "version": "1.0",
  "exportedAt": 1712700000000,
  "providerDefaults": [ /* provider setup records */ ],
  "presets": [ /* preset records */ ]
}
```

Import validation rejects packs with inline secrets.

## Next steps

See the [Customization Guide](../format/) for guidance on building role-specific presets and what to lock down for production.