dstack AI Orchestration Engine

0.20.17 · active · verified Thu Apr 16

dstack is an open-source orchestration engine for running AI workloads on any cloud or on-premises. It provides a CLI and Python client for managing resources, services, and ML runs. Currently at version 0.20.17, the library maintains an active release schedule with frequent minor updates focusing on performance, new backend integrations, and feature enhancements.

Common errors

```
dstack.errors.DstackError: Failed to connect to dstack server: Connection refused
```
cause The dstack server URL configured is incorrect, or the server is not running/unreachable.

fix Verify the `DSTACK_URL` environment variable or `dstack config get --url`. Ensure the dstack server is running and accessible from your machine, checking network connectivity and firewall rules.
```
dstack.errors.DstackError: Unauthorized
```
cause The provided DSTACK_API_KEY is missing, incorrect, or lacks the necessary permissions.

fix Verify the `DSTACK_API_KEY` environment variable or `dstack config get --key`. Generate a new API key if necessary via the dstack UI or CLI, and ensure it has the correct scope.
```
AttributeError: module 'dstack' has no attribute 'client'
```
cause Attempting to access the 'client' object as `dstack.client` after only importing the top-level `dstack` module.

fix Change your import statement to `from dstack.client import Client` to directly import the Client class.
```
yaml.YAMLError: while scanning a simple key
```
cause A dstack YAML configuration file (e.g., for a fleet or service) contains syntax errors, often due to incorrect indentation or missing colons/quotes.

fix Carefully review your YAML file for syntax errors, paying close attention to whitespace, indentation, and proper key-value separation. Use a YAML linter or validator to identify issues.

Warnings

breaking Configuration for Prefill-Decode (PD) disaggregation with SGLang changed in version 0.20.17.
Fix: If you are using SGLang with PD disaggregation, you must now configure the `router` property on the service replica group instead of on the gateway. Consult the updated documentation for service configuration examples.
gotcha dstack relies on proper authentication and server URL configuration. Client instantiation or API calls will fail without these.
Fix: Ensure `DSTACK_URL` and `DSTACK_API_KEY` environment variables are set, or configure them using the `dstack config set --url <URL> --key <KEY>` CLI command.
gotcha The YAML configuration schema for dstack resources (fleets, services, dev environments) can evolve between minor versions.
Fix: Always consult the official dstack documentation or release notes when upgrading to a new version to understand any changes to the YAML configuration format for your existing deployments.

Install

pip install dstack Install latest version

Imports

Client
wrong:
```
import dstack; client = dstack.client.Client()
```
correct:
```
from dstack.client import Client
```
The primary Python client is accessed directly from the 'dstack.client' submodule, not via a top-level 'dstack' import.

Quickstart

This quickstart demonstrates how to instantiate the dstack Python client and make a basic API call to verify connectivity and authentication by fetching the user's profile and listing projects. It assumes the dstack server URL and API key are configured via environment variables or the dstack CLI config file.

import os
from dstack.client import Client

# Configure dstack client via environment variables (DSTACK_URL, DSTACK_API_KEY)
# or the dstack config file (~/.dstack/config.yaml). For a runnable example,
# ensure these are set.
# Example: export DSTACK_URL="https://your-dstack-server.com"
# Example: export DSTACK_API_KEY="ds_your_api_key_here"

try:
    client = Client()
    # Attempt a simple API call to verify connection and authentication
    user_profile = client.get_profile() # Requires an authenticated client
    print(f"Successfully connected to dstack server as user: {user_profile.name} (ID: {user_profile.id})")

    # Example: List available projects
    projects = client.projects()
    print(f"Found {len(projects)} projects:")
    for project in projects:
        print(f"- {project.name} (ID: {project.id})")

except Exception as e:
    print(f"Error connecting to dstack or fetching data: {e}")
    print("Please ensure your dstack server URL (DSTACK_URL) and API Key (DSTACK_API_KEY) are correctly configured in your environment or dstack config file.")

view raw JSON →