Skip to content

Installation

Set up the server

The server can run on your laptop or any environment with access to the cloud and on-prem clusters you plan to use.

The server can be set up via uv on Linux, macOS, and Windows (via WSL 2). It requires Git and OpenSSH.

$ uv tool install "dstack[all]" -U
$ dstack server

Applying ~/.dstack/server/config.yml...

The admin token is "bbae0f28-d3dd-4820-bf61-8f4bb40815da"
The server is running at http://127.0.0.1:3000/

The server can be set up via pip on Linux, macOS, and Windows (via WSL 2). It requires Git and OpenSSH.

$ pip install "dstack[all]" -U
$ dstack server

Applying ~/.dstack/server/config.yml...

The admin token is "bbae0f28-d3dd-4820-bf61-8f4bb40815da"
The server is running at http://127.0.0.1:3000/

$ docker run -p 3000:3000 \
    -v $HOME/.dstack/server/:/root/.dstack/server \
    dstackai/dstack

Applying ~/.dstack/server/config.yml...

The admin token is "bbae0f28-d3dd-4820-bf61-8f4bb40815da"
The server is running at http://127.0.0.1:3000/

For more details on server deployment options, see the Server deployment guide.

Configure backends

To orchestrate compute across GPU clouds or Kubernetes clusters, you need to configure backends.

Set up the CLI

Once the server is up, you can access it via the dstack CLI.

The CLI can be used on Linux, macOS, and Windows. It requires Git and OpenSSH.

$ uv tool install dstack -U

$ pip install dstack -U
Windows

To use the CLI on Windows, ensure you've installed Git and OpenSSH via Git for Windows.

When installing it, ensure you've checked Git from the command line and also from 3-rd party software (or Use Git and optional Unix tools from the Command Prompt), and Use bundled OpenSSH.

Shell autocompletion

dstack supports shell autocompletion for bash and zsh.

First, validate if completion scripts load correctly in your current shell session:

$ eval "$(dstack completion bash)"

If completions work as expected and you would like them to persist across shell sessions, add the completion script to your shell profile using these commands:

$ mkdir -p ~/.dstack
$ dstack completion bash > ~/.dstack/completion.sh
$ echo 'source ~/.dstack/completion.sh' >> ~/.bashrc

First, validate if completion scripts load correctly in your current shell session:

$ eval "$(dstack completion zsh)"

If completions work as expected and you would like them to persist across shell sessions, you can install them via Oh My Zsh using these commands:

$ mkdir -p ~/.oh-my-zsh/completions
$ dstack completion zsh > ~/.oh-my-zsh/completions/_dstack

And if you don't use Oh My Zsh:

$ mkdir -p ~/.dstack
$ dstack completion zsh > ~/.dstack/completion.sh
$ echo 'source ~/.dstack/completion.sh' >> ~/.zshrc

If you get an error similar to 2: command not found: compdef, then add the following line to the beginning of your ~/.zshrc file: autoload -Uz compinit && compinit.

Configure the default project

To point the CLI to the dstack server, configure it with the server address, user token, and project name:

$ dstack project add \
    --name main \
    --url http://127.0.0.1:3000 \
    --token bbae0f28-d3dd-4820-bf61-8f4bb40815da

Configuration is updated at ~/.dstack/config.yml

This configuration is stored in ~/.dstack/config.yml.

Install agent skills

Install skills to help AI agents use the dstack CLI and edit configuration files.

$ npx skills add dstackai/dstack

Agent skills are experimental. Share your feedback via GitHub issues.

What's next?

  1. See Backends
  2. Follow Quickstart
  3. Check the server deployment guide