dstack 0.20 GA: Fleet-first UX and other important changes¶
We’re releasing dstack 0.20.0, a major update that improves how teams orchestrate GPU workloads for development, training, and inference. Most dstack updates are incremental and backward compatible, but this version introduces a few major changes to how you work with dstack.
In dstack 0.20.0, fleets are now a first-class concept, giving you more explicit control over how GPU capacity is provisioned and managed. We’ve also added Events, which record important system activity—such as scheduling decisions, run status changes, and resource lifecycle updates—so it’s easier to understand what’s happening without digging through server logs.
This post goes through the changes in detail and explains how to upgrade and migrate your existing setup.
Fleets¶
In earlier versions, submitting a run that didn’t match any existing fleet would cause dstack to automatically create one. While this reduced setup overhead, it also made capacity provisioning implicit and less predictable.
With dstack 0.20.0, fleets must be created explicitly and treated as first-class resources. This shift makes capacity provisioning declarative, improving control over resource limits, instance lifecycles, and overall fleet behavior.
For users who previously relied on auto-created fleets, similar behavior can be achieved by defining an elastic fleet, for example:
type: fleet
# The name is optional, if not specified, generated randomly
name: default
# Can be a range or a fixed number
# Allow to provision up to 2 instances
nodes: 0..2
# Uncomment to ensure instances are inter-connected
#placement: cluster
# Deprovision instances above the minimum if they remain idle
idle_duration: 1h
resources:
# Allow to provision up to 8 GPUs
gpu: 0..8
If the nodes range starts above 0, dstack provisions the initial capacity upfront and scales additional instances on demand, enabling more predictable capacity planning.
When a run does not explicitly reference a fleet (via the fleets property), dstack automatically selects one that satisfies the run’s requirements.
Events¶
Previously, when dstack changed the state of a run or other resource, that information was written only to the server logs. This worked for admins, but it made it hard for users to understand what happened or why.
Starting with version 0.20.0, dstack exposes these events directly to users.
Each resource now includes an Events tab in the UI, showing related events in real time:
There is also a dedicated Events page that aggregates events across resources. You can filter by project, user, run, or job to quickly narrow down what you’re looking for:
The same information is available through the CLI:
This makes it easier to track state changes, debug issues, and review past actions without needing access to server logs.
Runs¶
This release updates several defaults related to run configuration. The goal is to reduce implicit assumptions and make it more convenient.
Working directory¶
Previously, the working_dir property defaulted to /workflow. Now, the default working directory is always taken from the Docker image.
The working directory in the default Docker images (if you don't specify image) is now set to /dstack/run.
Repo directory¶
Previously, if you didn't specify a repo path, the repo was cloned to /workflow. Now, in that case the repo will be cloned to the working directory.
type: dev-environment
name: vscode
repos:
# Clones the repo from the parent directory (`examples/..`) to `<working dir>`
- ..
ide: vscode
Also, now if the repo directory is not empty, the run will fail with an error.
Backward compatibility¶
While the update introduces breaking changes, 0.19. CLIs remain compatible with 0.20. servers.
Note, the 0.20. CLI only works with a 0.20. server.
Breaking changes
This release introduces breaking changes that may affect existing setups. Before upgrading either the CLI or the server, review the migration guide.
What's next¶
- Follow the Installation guide
- Try the Quickstart
- Report issues on GitHub
- Ask questions on Discord