# Settings
Settings is where you wire up the infrastructure behind every agent launch. Define which AI providers are available, create reusable presets that encode exactly how agents should run, and import or export packs to standardize your setup. **Configure once, launch confidently every time.**

## What this page covers

- **Agent Presets** — Create, edit, export, and import launcher configurations
- **Providers** — Register AI providers and manage model availability
- **Valdr Packs** — Import and export packs for portable agent configurations

---

## Agent Presets

Agent presets are saved launcher configurations. Each preset bundles a provider, model, worktree policy, environment references, and runtime config into a reusable one-click launch target. Instead of re-configuring every agent session from scratch, you pick a preset and go.

{{< thumbcard src="/images/ui/settings/agent-presets-tab.png" alt="Agent Presets table showing configured presets with provider and environment references" caption="All your launcher presets in one place — pick a provider, set it up once, reuse everywhere" >}}

### Preset table columns

| Column | What it shows |
|--------|---------------|
| **Key** | Unique identifier for the preset (e.g., `coder-claude`, `orchestrator-ollama`). Used when launching agents from the UI or via MCP. |
| **Provider** | The AI provider this preset targets, shown with its icon (e.g., Claude, Codex, Ollama). |
| **Env refs** | Environment variable names the preset needs at runtime (e.g., `CODEX_API_KEY`). A dash means no env refs required. |

### Creating a preset

Click the **+** button in the toolbar to open the preset form. Every field shapes how agents behave when launched with this preset:

{{< thumbcard src="/images/ui/settings/preset-edit-form.png" alt="Preset editor form showing key, provider, model, config JSON, and worktree options" caption="Full control over every launch parameter — provider, model, permissions, worktree isolation, and runtime config" >}}

| Field | Purpose |
|-------|---------|
| **Key** | A unique slug that identifies this preset. Set once at creation, immutable afterward. Choose something descriptive: `coder-claude`, `reviewer-codex`, `orchestrator-ollama`. |
| **Display name** | Human-readable label shown in launcher dropdowns (e.g., "Claude Coder"). |
| **Provider** | Which registered provider to use. The dropdown shows all providers from the Providers tab. |
| **Model** | Which model to use from the selected provider's model list (e.g., Opus, Sonnet, gpt-5.4). |
| **Description** | Optional note about what this preset is for. Helps when you have many presets. |
| **Env refs** | Comma-separated environment variable names the agent session needs (e.g., `CODEX_API_KEY, OPENAI_API_KEY`). Valdr passes these references through to the agent runtime. Treat raw session metadata and spec exports as sensitive if they include provider settings. |
| **Config JSON** | Raw JSON configuration passed to the agent launcher. Controls permission modes, allowed tools, keep-alive timeouts, and other runtime behavior. |

### Worktree options

The three checkboxes at the bottom of the preset form control git worktree behavior:

| Option | What it does |
|--------|--------------|
| **Create worktree by default** | When checked, every agent session launched with this preset gets its own isolated git worktree. Changes stay off your active branch until you review and merge. |
| **Allow reuse existing worktree** | When checked, agents can reuse a worktree from a previous session instead of creating a fresh one. Useful for multi-step workflows on the same branch. |
| **Allow ad-hoc overrides** | When checked, users can override worktree settings per-launch. When unchecked, the preset's defaults are enforced. |

{{< callout type="tip" >}}
**Keep worktree creation on by default.** Isolated worktrees reduce branch-level blast radius and make review easier before you merge changes back. They are a workflow boundary, not an OS sandbox.
{{< /callout >}}

### Export and import

Use the **Export** and **Import** buttons to move presets between machines or share them with teammates.

- **Export** saves all presets (or a selection) as a portable file
- **Import** loads presets from a file, with conflict detection if a key already exists

This makes onboarding fast — set up presets once, export, and every team member imports the same configuration. Combined with [Valdr Packs](/valdr/docs/valdr-packs/) and [provider/preset configuration](/valdr/docs/valdr-provider-packs/), you can standardize an entire team's agent infrastructure in minutes.

---

## Providers

The Providers tab is where you register the AI providers Valdr can use. Each provider entry defines a connection type, available models, and a default model. Agent presets reference these providers, so **providers must be registered before you can create presets that use them.**

{{< thumbcard src="/images/ui/settings/providers-tab.png" alt="Providers table showing Claude Code, Codex, and Ollama Local with model counts and enabled status" caption="Three providers configured — cloud and local models side by side, each with its own model roster" >}}

### Provider table columns

| Column | What it shows |
|--------|---------------|
| **Provider** | Display name and icon (e.g., Claude Code, Codex, Ollama Local). |
| **Type** | The provider integration type (e.g., `claude`, `codex`, `ollama`). Determines how Valdr communicates with the provider. |
| **Enabled** | Whether this provider is available for use in presets and launches. Disable a provider to temporarily remove it without deleting the configuration. |
| **Default Model** | The model used when no specific model is selected (e.g., `sonnet`, `gpt-5.4`, `qwen3-coder-next`). |
| **Models** | How many models are registered under this provider. Click Edit to see and manage the full model list. |

### Adding a provider

Click **+** to register a new provider. You need:

1. **A display name** — what you see in dropdowns and tables
2. **A type** — the integration protocol (`claude`, `codex`, `ollama`, etc.)
3. **At least one model** — the models available through this provider
4. **A default model** — which model to use when none is specified

### Mixing cloud and local providers

Valdr treats all providers equally. Run Claude for complex coding tasks and Ollama for fast local iteration — switch between them by choosing a different preset. This gives you:

- **Cost control** — use cheaper or free local models for exploratory work
- **Offline capability** — Ollama presets work without internet
- **Comparison** — run the same task with different providers and compare session quality in the [Agent Sessions](/valdr/docs/ui/agent-sessions/) view

### Export and import

Like presets, providers support **Export** and **Import** for portable configuration. Export your provider setup and share the JSON so teammates import identical provider configurations. See [Provider Configuration](/valdr/docs/valdr-provider-packs/overview/) for the full JSON format.

---

## Valdr Packs

The Valdr Packs tab handles import and export of `.valdr-pack.tar.gz` archives — portable bundles that package agents, prompts, capabilities, and configuration into a single shareable file.

{{< thumbcard src="/images/ui/settings/valdr-packs-tab.png" alt="Valdr Pack import/export panel with pack key selector and agent handle filter" caption="Export your entire agent setup as a portable archive — import it on another machine and be productive immediately" >}}

### Exporting a pack

1. **Select pack keys** — choose which packs to include in the export (e.g., `valdr`)
2. **Filter by agent handles** (optional) — limit the export to specific agents (e.g., `@executor`, `@reviewer`)
3. Click **Export Pack** to generate the `.valdr-pack.tar.gz` archive

The exported archive includes all agents, prompts, capabilities, and configuration associated with the selected packs.

### Importing a pack

Click **Import Pack** to load an archive. Valdr runs a **conflict-aware preflight check** before committing any changes:

- Detects naming conflicts with existing agents, prompts, or capabilities
- Shows what will be added, updated, or skipped
- Requires explicit confirmation before applying changes

This means you can safely import packs without worrying about overwriting your existing setup.

{{< callout type="info" >}}
Valdr Packs are the fastest way to standardize agent configurations across machines. Export once, import everywhere — every machine gets the same agents, prompts, and capabilities. Learn more about pack authoring in the [Valdr Packs guide](/valdr/docs/valdr-packs/).
{{< /callout >}}

---

## How settings flow into agent launches

Settings aren't just configuration — they're the foundation of every agent session. Here's how the pieces connect:

1. **Register providers** in the Providers tab (e.g., Claude, Codex, Ollama)
2. **Create presets** in Agent Presets that reference those providers with specific models and runtime config
3. **Launch agents** from [Tasks](/valdr/docs/ui/tasks/agent-launch/) or the [Orchestrator](/valdr/docs/ui/orchestrator/) using your presets
4. **Review results** in [Agent Sessions](/valdr/docs/ui/agent-sessions/) — every session records which preset and provider was used

Change a preset once and every future launch inherits the update. No re-configuring, no drift, no "which model was that session using?" questions.

---

## Next steps

Ready to put your settings to work? [Launch your first agent from a task](/valdr/docs/ui/tasks/agent-launch/) and see how presets turn configuration into one-click execution.