Skip to content

0.20.0

Choose a tag to compare

View all tags
@r4victor r4victor released this 17 Dec 11:33
· 44 commits to master since this release
0.20.0
9ea6bf7
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

dstack 0.20 is a major release that brings significant improvements and introduces a number of breaking changes. Read below for the most important ones. For migration notes, please refer to the migration guide.

Fleets

dstack previously had two different ways to provision instances for runs: using a fleet configuration or using automatic fleet provisioning on run apply. To unify the UX, dstack no longer creates fleets automatically.

Fleets must now be created explicitly before submitting runs. This gives users full control over the provisioning lifecycle. If you don't need any limits on instance provisioning (as was the case with auto-created fleets), you can create a single elastic fleet for all runs:

type: fleet
name: default-fleet
nodes: 0..

Note that multi-node tasks require fleets with placement: cluster, which provides the best possible connectivity. You will need a separate fleet for each cluster.

Note

To keep the old behavior with auto-created fleets, set the DSTACK_FF_AUTOCREATED_FLEETS_ENABLED environment variable.

Runs

Working directory

Previously, the working_dir property had complicated semantics: it defaulted to /workflow, but for tasks and services without commands, the image's working directory was used instead.

This has now been simplified: working_dir always defaults to the image's working directory. The working directory of the default dstack images is now set to /dstack/run.

Repo directory

Working with repos is now more explicit and intuitive. First, dstack now only sets up repos that are explicitly defined in run configurations via repos; repos initialized with dstack init are not set up unless specified:

type: dev-environment
ide: vscode
repos:
  # Clone the repo in the configuration's dir into `working_dir`
  - .

Second, repos[].path now defaults to working_dir (".") instead of /workflow.

Third, cloning a repo into a non-empty directory now raises an error so that mistakes are not silently ignored. The previous behavior of skipping cloning can be specified explicitly with if_exists: skip:

type: dev-environment
ide: vscode
repos:
  - local_path: .
    path: /my_volume/repo
    if_exists: skip

Events

dstack now stores important events—such as resource CRUD operations, status changes, and other information crucial for auditing and debugging. Users can view events using the dstack event CLI command or in the UI.

$ dstack event
[2025-12-11 15:05:20] [👤admin] [run clever-cheetah-1] Run submitted. Status: SUBMITTED
[2025-12-11 15:05:20] [job clever-cheetah-1-0-0] Job created on run submission. Status: SUBMITTED
[2025-12-11 15:05:26] [job clever-cheetah-1-0-0, instance cloud-fleet-0] Job assigned to instance. Instance status: BUSY (1/1 blocks busy)

CLI

JSON output

The dstack ps and dstack gateway commands now support --format json / --json arguments that print results in JSON instead of plaintext:

$ dstack ps --json
{
  "project": "main",
  "runs": [
    {
      "id": "5f2e08b5-2098-4064-86c7-0efe0eb84970",
      "project_name": "main",
      "user": "admin",
      "fleet": {
        "id": "9598d5db-67d8-4a2e-bdd2-842ab93b2f2e",
        "name": "cloud-fleet"
      },
      ...
    }
  ]
}

Verda (formerly Datacrunch)

The datacrunch backend has been renamed to verda, following the company's rebranding.

projects:
  - name: main
    backends:
      - type: verda
        creds:
          type: api_key
          client_id: xfaHBqYEsArqhKWX-e52x3HH7w8T
          client_secret: B5ZU5Qx9Nt8oGMlmMhNI3iglK8bjMhagTbylZy4WzncZe39995f7Vxh8

Gateways

Gateway configurations now support an optional instance_type property that allows overriding the default gateway instance type:

type: gateway
name: example-gateway

backend: aws
region: eu-west-1

instance_type: t3.large

domain: example.com

Currently instance_type is supported for aws and gcp backends.

All breaking changes

  • Fleets are no longer created automatically on run apply and have to be created explicitly before submitting runs.
  • The run's working_dir now always defaults to the image's working directory instead of /workflow. The working directory of dstack default images is now /dstack/run.
  • repos[].path now defaults to working_dir (".") instead of /workflow.
  • Dropped implicitly loaded repos; repos must be specified via repos configuration property.
  • Cloning a repo into a non-empty directory now raises an error. This can be changed by setting if_exists: skip.
  • Dropped CLI commands dstack config, dstack stats, and dstack gateway create.
  • Dropped Python API RunCollection methods RunCollection.get_plan(), RunCollection.exec_plan(), and RunCollection.submit().
  • Dropped local repos support: dstack init --local and dstack.api.LocalRepo.
  • Dropped Azure deprecated VM series Dsv3 and Esv4.
  • Dropped legacy server environment variables DSTACK_SERVER_METRICS_TTL_SECONDS and DSTACK_FORCE_BRIDGE_NETWORK.

Deprecations

  • Deprecated the API endpoint /api/project/{project_name}/fleets/create in favor of /api/project/{project_name}/fleets/apply.
  • Deprecated repo_dir argument in RunCollection.get_run_plan() in favor of repos[].path.

What's Changed

New Contributors

Full Changelog: 0.19.40...0.20.0

Contributors

un-def, olgenn, and 4 other contributors
Assets 2
Loading