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:

{
  "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 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.

"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:

Resolve env sentinels

Preset config values can reference environment entries:

{ "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"`

Examples

Claude — coding preset

{
  "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

{
  "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

{
  "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:

{
  "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 for guidance on building role-specific presets and what to lock down for production.

Provider Configuration Customization Guide