Skip to content

[Presets] CLI refactoring #4152

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
peterschmidt85 merged 3 commits into from
Aug 17, 2026
Merged

[Presets] CLI refactoring #4152

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a643d7d
[Presets] Preset status, in-flight get, and preset export
Aug 17, 2026
44899e6
[Presets] Make preset a first-class apply configuration
Aug 17, 2026
5151127
[Presets] Fix preset list typing pyright reported
Aug 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 33 additions & 24 deletions mkdocs/docs/concepts/presets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ To get the best performance for the given model, hardware, and other constraints

Creating a preset requires the `claude` CLI to be installed on the machine where you create a preset.

## Create a preset
## Apply a configuration

First, define a preset configuration as a YAML file in your project folder.
The filename must end with `.dstack.yml` (e.g. `.dstack.yml` or `preset.dstack.yml` are both acceptable).
Expand Down Expand Up @@ -53,12 +53,12 @@ env:

</div>

To create the preset, pass the configuration to the `dstack preset create` command:
To create the preset, pass the configuration to the `dstack apply` command:

<div class="termy">

```shell
$ dstack preset create -f preset.dstack.yml --fleet b200-fleet
$ dstack apply -f preset.dstack.yml --fleet b200-fleet
Create the preset dsv4-flash? [y/n]: y
[2026-08-04 11:38:34] Starting preset creation for deepseek-ai/DeepSeek-V4-Flash. Allowed fleets: b200-fleet.
[2026-08-04 12:31:19] Trial 3 switched from vLLM to SGLang: 319 tok/s per user, 2.2x the baseline.
Expand All @@ -69,22 +69,22 @@ Create the preset dsv4-flash? [y/n]: y
</div>

> It's highly recommended to specify the exact hardware you want the preset to use, so that the
> optimization is done against that hardware. Point `dstack preset create` to a fleet configured
> optimization is done against that hardware. Point `dstack apply` to a fleet configured
> correspondingly, via `fleets` inside the preset configuration or via `--fleet` in the CLI.

The command executes entirely locally and uses the locally installed `claude` CLI along with `dstack`'s bundled skills. The agent uses a `dstack` task to find the best serving configuration for the available fleet offers, then submits it as a `dstack` service for a final benchmark.

You can stop watching with `Ctrl`+`C` at any time. The agent keeps running, and `dstack preset logs -f` follows it again. Resume an interrupted creation with `dstack preset create --resume`:
You can stop watching with `Ctrl`+`C` at any time. The agent keeps running, and `dstack preset logs -f` follows it again. Resume an interrupted creation with `dstack preset resume`:

<div class="termy">

```shell
$ dstack preset create -f preset.dstack.yml --resume a1b2c3d4
$ dstack preset resume a1b2c3d4
```

</div>

When resuming, the constraints are read from the original session, not from the configuration file. Editing them and resuming has no effect. To change any of them, create a new preset.
When resuming, the configuration and constraints are read from the original session. To change any of them, create a new preset.

To stop a creation and its runs, use `dstack preset stop`.

Expand Down Expand Up @@ -113,7 +113,7 @@ To stop a creation and its runs, use `dstack preset stop`.

Set `fleets` to restrict creation and reuse to specific [fleets](fleets.md). It's highly recommended to specify a fleet with exactly the hardware that you'd like the preset to use.

Alternatively, pass `--fleet` to `dstack preset create` or `dstack preset apply`.
Alternatively, pass `--fleet` to `dstack apply`.

> Profile settings such as `spot_policy`, `max_price`, and `backends` are ignored during preset
> creation. Configure them on the fleet instead.
Expand Down Expand Up @@ -149,7 +149,7 @@ previous:

</div>

Alternatively, pass `--previous` (repeatable) to `dstack preset create`.
Alternatively, pass `--previous` (repeatable) to `dstack apply`.

### Prompt

Expand Down Expand Up @@ -201,14 +201,25 @@ When the session builds on `previous`, the baseline trial reproduces the best co
!!! info "Reference"
The `preset` configuration supports many more options. See the [`.dstack.yml` reference](../reference/dstack.yml/preset.md).

## Apply a preset
## Export a preset

To deploy a preset as a service, pass the preset configuration and the preset ID to the `dstack preset apply` command:
To deploy a preset, export it as a service configuration with `dstack preset export`:

<div class="termy">

```shell
$ dstack preset apply -f preset.dstack.yml --id c83375b4
$ dstack preset export c83375b4 -f qwen.dstack.yml
Preset c83375b4 exported to qwen.dstack.yml (16 files). Deploy it with `dstack apply -f qwen.dstack.yml`
```

</div>

The command writes the service configuration along with any files it references, such as patches. Set the service `name` and, optionally, a [gateway](gateways.md) in the exported configuration, then submit it with `dstack apply`:

<div class="termy">

```shell
$ dstack apply -f qwen.dstack.yml
Project main
User admin
Type service
Expand All @@ -218,8 +229,6 @@ $ dstack preset apply -f preset.dstack.yml --id c83375b4
Retry policy off
Idle duration 5m
Max duration off
Model deepseek-ai/DeepSeek-V4-Flash (base)
Preset c83375b4 (io=10000/1500 conc=1 tok/s/user=309 tok/s=296 ttft=213ms ctx=1M)

# BACKEND RESOURCES INSTANCE TYPE PRICE
1 runpod (US-CA-2) cpu=48 mem=502GB disk=500GB gpu=B200:180GB:2 NVIDIA B200 $11.78
Expand All @@ -239,8 +248,8 @@ Use `dstack preset` to list presets:

```shell
$ dstack preset list
ID BASE GPU CONSTRAINTS BENCHMARK STATUS SUBMITTED
c83375b4 deepseek-ai/DeepSeek-V4-Flash B200:180GB:2 io=10000/1500 conc=1 tok/s/user=309 ttft=213ms ctx=1M ▂▁██▇ trialing (5/5) 2 min ago
NAME ID BASE CONSTRAINTS BENCHMARK STATUS SUBMITTED
dsv4-flash-b200 c83375b4 deepseek-ai/DeepSeek-V4-Flash io=10K/1.5K c=1 tps/user=309 ttft=213ms ctx=1M ▂▁██▇ trialing (5/5) 2 min ago
```

</div>
Expand All @@ -251,16 +260,16 @@ By default, `dstack preset` shows creations that are still running, or the most

```shell
$ dstack preset list -a
ID BASE GPU CONSTRAINTS BENCHMARK STATUS SUBMITTED
c83375b4 deepseek-ai/DeepSeek-V4-Flash B200:180GB:2 io=10000/1500 conc=1 tok/s/user=309 ttft=213ms ctx=1M ▂▁██▇ trialing (5/5) 2 min ago
092c792b Qwen/Qwen3.5-397B-A17B RTXPRO6000:4 io=8K/1K conc=64 tok/s/user=19.6 ttft=3.43s ctx=32K ▁▂▅▇█·· verified (7) 3 days ago
9ab0fa65 Qwen/Qwen3.6-27B RTXPRO4500:1 io=1K/1K conc=8 tok/s/user=57.1 ttft=499ms ctx=128K ▁▄██▆·█ verified (7) 4 days ago
f91d6b60 Qwen/Qwen3-32B RTX5090:32GB:1 io=1K/512 conc=8 tok/s/user=85.8 ttft=368ms ctx=32K ▁▁▅▅▄▅▇▄▇█ verified (10) 2 weeks ago
NAME ID BASE CONSTRAINTS BENCHMARK STATUS SUBMITTED
dsv4-flash-b200 c83375b4 deepseek-ai/DeepSeek-V4-Flash io=10K/1.5K c=1 tps/user=309 ttft=213ms ctx=1M ▂▁██▇ trialing (5/5) 2 min ago
qwen35-pro6000 092c792b Qwen/Qwen3.5-397B-A17B io=8K/1K c=64 tps/user=19.6 ttft=3.43s ctx=32K ▁▂▅▇█·· verified (7) 3 days ago
qwen36-pro4500 9ab0fa65 Qwen/Qwen3.6-27B io=1K/1K c=8 tps/user=57.1 ttft=499ms ctx=128K ▁▄██▆·█ verified (7) 4 days ago
qwen3-32b-5090 f91d6b60 Qwen/Qwen3-32B io=1K/512 c=8 tps/user=85.8 ttft=368ms ctx=32K ▁▁▅▅▄▅▇▄▇█ verified (10) 2 weeks ago
```

</div>

The `CONSTRAINTS` column is what the creation was asked for, and `BENCHMARK` is the best trial so far. `tok/s/user` is the steady decode rate, measured as one second divided by the median time per output token, so it excludes the time to the first token.
The `CONSTRAINTS` column is what the creation was asked for, and `BENCHMARK` is the best trial so far. `tps/user` is the steady decode rate, measured as one second divided by the mean time per output token, so it excludes the time to the first token.

The glyphs after the benchmark are one per trial: height is throughput, a yellow bar is a trial whose benchmark broke a constraint, and a red `·` is one that produced no benchmark at all. The shape shows whether a run converged or wandered.

Expand All @@ -283,12 +292,12 @@ $ dstack preset delete c83375b4

## Troubleshooting

To trace the agent's activity, pass `--debug` to `dstack preset create`:
To trace the agent's activity, pass `--debug` to `dstack apply`:

<div class="termy">

```shell
$ dstack preset create -f preset.dstack.yml --debug
$ dstack apply -f preset.dstack.yml --debug
```

</div>
Expand Down
27 changes: 22 additions & 5 deletions mkdocs/docs/reference/cli/dstack/preset.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# dstack preset

The `dstack preset` commands create, list, apply, and delete local
The `dstack preset` commands create, list, export, and delete local
[presets](../../../concepts/presets.md).

## dstack preset list
Expand All @@ -20,6 +20,8 @@ $ dstack preset list --help

## dstack preset create

> Deprecated: pass a preset configuration to [`dstack apply`](apply.md) instead.

The `dstack preset create` command uses an agent to create and save a
verified preset from a preset configuration.

Expand Down Expand Up @@ -97,17 +99,32 @@ $ dstack preset get --help

</div>

## dstack preset apply
## dstack preset resume

The `dstack preset resume` command resumes an interrupted preset creation.

##### Usage

<div class="termy">

```shell
$ dstack preset resume --help
#GENERATE#
```

</div>

## dstack preset export

The `dstack preset apply` command selects a matching local preset and
submits its service.
The `dstack preset export` command exports a preset as a service
configuration that `dstack apply` deploys.

##### Usage

<div class="termy">

```shell
$ dstack preset apply --help
$ dstack preset export --help
#GENERATE#
```

Expand Down
8 changes: 4 additions & 4 deletions mkdocs/docs/reference/dstack.yml/preset.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ used to create or apply a [preset](../../concepts/presets.md).

## Root reference

#SCHEMA# dstack._internal.cli.models.configurations.PresetConfiguration
#SCHEMA# dstack._internal.core.models.presets.PresetConfiguration
overrides:
show_root_heading: false
type:
Expand All @@ -17,7 +17,7 @@ used to create or apply a [preset](../../concepts/presets.md).

Allows the creation agent to select a compatible model variant.

#SCHEMA# dstack._internal.cli.models.configurations.PresetModelBase
#SCHEMA# dstack._internal.core.models.presets.PresetModelBase
overrides:
show_root_heading: false

Expand All @@ -26,15 +26,15 @@ used to create or apply a [preset](../../concepts/presets.md).
Requires an exact model repo or path and optionally sets another
client-facing model name.

#SCHEMA# dstack._internal.cli.models.configurations.PresetModelRepo
#SCHEMA# dstack._internal.core.models.presets.PresetModelRepo
overrides:
show_root_heading: false

### `prompt`

Custom agent instructions. Set to an inline string, or to a file:

#SCHEMA# dstack._internal.cli.models.configurations.PresetPromptFile
#SCHEMA# dstack._internal.core.models.presets.PresetPromptFile
overrides:
show_root_heading: false

Expand Down
Loading
Loading