[Blog] dstack 0.20 GA: Fleet-first UX and other important changes (#3401)

Author: peterschmidt85

docs/blog/posts/0_20.md

@@ -0,0 +1,127 @@
+---
+title: "dstack 0.20 GA: Fleet-first UX and other important changes"
+date: 2025-12-18
+description: "TBA"  
+slug: "0_20"
+image: https://dstack.ai/static-assets/static-assets/images/dstack-0_20.png
+categories:
+  - Changelog
+links:
+  - Release notes: https://github.com/dstackai/dstack/releases/tag/0.20.0
+  - Migration guide: https://dstack.ai/docs/guides/migration/#0_20
+---
+
+# 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.
+
+<img src="https://dstack.ai/static-assets/static-assets/images/dstack-0_20.png" width="630" />
+
+This post goes through the changes in detail and explains how to upgrade and migrate your existing setup.
+
+<!-- more -->
+
+## 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:
+
+<div editor-title="fleet.dstack.yml">
+    
+    ```yaml
+    type: fleet
+    # The name is optional, if not specified, generated randomly
+    name: default
+    
+    # Can be a range or a fixed number
+    # Allow to provision of 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
+    ```
+    
+</div>
+
+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`](../../docs/reference/dstack.yml/dev-environment.md#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:
+
+<img src="https://dstack.ai/static-assets/static-assets/images/dstack-event-ui-run.png" width="750" />
+
+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:
+
+<img src="https://dstack.ai/static-assets/static-assets/images/dstack-event-ui-all.png" width="750" />
+
+The same information is available through the CLI:
+
+<img src="https://dstack.ai/static-assets/static-assets/images/dstack-event-cli.png" width="750" />
+
+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.
+
+<div editor-title="examples/.dstack.yml"> 
+
+```yaml
+type: dev-environment
+name: vscode    
+
+repos:
+  # Clones the repo from the parent directory (`examples/..`) to `<working dir>`
+  - ..
+
+ide: vscode
+```
+
+</div>
+
+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.
+
+!!! warning "Breaking changes"
+    This release introduces breaking changes that may affect existing setups. Before upgrading either the CLI or the server, review the [migration guide](https://dstack.ai/docs/guides/migration/#0_20).
+
+## What's next
+
+1. Follow the [Installation](../../docs/installation/index.md) guide
+2. Try the [Quickstart](../../docs/quickstart.md)
+3. Report issues on [GitHub](https://github.com/dstackai/dstack/issues)
+4. Ask questions on [Discord](https://discord.gg/u8SmfwPpMd)