{"id":8966,"library":"dstack","title":"dstack AI Orchestration Engine","description":"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.","status":"active","version":"0.20.17","language":"en","source_language":"en","source_url":"https://github.com/dstackai/dstack","tags":["AI/ML orchestration","cloud computing","MLOps","resource management","GPU management"],"install":[{"cmd":"pip install dstack","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary Python client is accessed directly from the 'dstack.client' submodule, not via a top-level 'dstack' import.","wrong":"import dstack; client = dstack.client.Client()","symbol":"Client","correct":"from dstack.client import Client"}],"quickstart":{"code":"import os\nfrom dstack.client import Client\n\n# Configure dstack client via environment variables (DSTACK_URL, DSTACK_API_KEY)\n# or the dstack config file (~/.dstack/config.yaml). For a runnable example,\n# ensure these are set.\n# Example: export DSTACK_URL=\"https://your-dstack-server.com\"\n# Example: export DSTACK_API_KEY=\"ds_your_api_key_here\"\n\ntry:\n    client = Client()\n    # Attempt a simple API call to verify connection and authentication\n    user_profile = client.get_profile() # Requires an authenticated client\n    print(f\"Successfully connected to dstack server as user: {user_profile.name} (ID: {user_profile.id})\")\n\n    # Example: List available projects\n    projects = client.projects()\n    print(f\"Found {len(projects)} projects:\")\n    for project in projects:\n        print(f\"- {project.name} (ID: {project.id})\")\n\nexcept Exception as e:\n    print(f\"Error connecting to dstack or fetching data: {e}\")\n    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.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Configuration for Prefill-Decode (PD) disaggregation with SGLang changed in version 0.20.17.","severity":"breaking","affected_versions":">=0.20.17"},{"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.","message":"dstack relies on proper authentication and server URL configuration. Client instantiation or API calls will fail without these.","severity":"gotcha","affected_versions":"All 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.","message":"The YAML configuration schema for dstack resources (fleets, services, dev environments) can evolve between minor versions.","severity":"gotcha","affected_versions":"All versions (especially across minor updates)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The dstack server URL configured is incorrect, or the server is not running/unreachable.","error":"dstack.errors.DstackError: Failed to connect to dstack server: Connection refused"},{"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.","cause":"The provided DSTACK_API_KEY is missing, incorrect, or lacks the necessary permissions.","error":"dstack.errors.DstackError: Unauthorized"},{"fix":"Change your import statement to `from dstack.client import Client` to directly import the Client class.","cause":"Attempting to access the 'client' object as `dstack.client` after only importing the top-level `dstack` module.","error":"AttributeError: module 'dstack' has no attribute 'client'"},{"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.","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.","error":"yaml.YAMLError: while scanning a simple key"}]}