Skip to content

CLI

Commands

dstack server

This command starts the dstack server.

$ dstack server --help
Usage: dstack server [-h] [--host HOST] [-p PORT] [-l LOG_LEVEL] [--default]
                     [--no-default] [--token TOKEN]

Options:
  -h, --help            Show this help message and exit
  --host HOST           Bind socket to this host. Defaults to 127.0.0.1
  -p, --port PORT       Bind socket to this port. Defaults to 3000.
  -l, --log-level LOG_LEVEL
                        Server logging level. Defaults to INFO.
  --default             Update the default project configuration
  --no-default          Do not update the default project configuration
  --token TOKEN         The admin user token

dstack init

This command initializes the current folder as a repo.

$ dstack init --help
Usage: dstack init [-h] [--project PROJECT] [-t OAUTH_TOKEN]
                   [--git-identity SSH_PRIVATE_KEY]
                   [--ssh-identity SSH_PRIVATE_KEY] [--local]

Options:
  -h, --help            Show this help message and exit
  --project PROJECT     The name of the project
  -t, --token OAUTH_TOKEN
                        An authentication token for Git
  --git-identity SSH_PRIVATE_KEY
                        The private SSH key path to access the remote repo
  --ssh-identity SSH_PRIVATE_KEY
                        The private SSH key path for SSH tunneling
  --local               Do not use git
Git credentials

If the current folder is a Git repo, the command authorizes dstack to access it. By default, the command uses the default Git credentials configured for the repo. You can override these credentials via --token (OAuth token) or --git-identity.

Custom SSH key

By default, this command generates an SSH key that will be used for port forwarding and SSH access to running workloads. You can override this key via --ssh-identity.

dstack run

This command runs a given configuration.

$ dstack run . --help
Usage: dstack run [--project NAME] [-h [TYPE]] [-f FILE] [-n RUN_NAME] [-d]
                  [-y] [--max-offers MAX_OFFERS] [--profile NAME]
                  [--max-price PRICE] [--max-duration DURATION] [-b NAME]
                  [-r NAME] [--instance-type NAME]
                  [--pool POOL_NAME | --reuse | --dont-destroy | --idle-duration IDLE_DURATION | --instance NAME]
                  [--spot | --on-demand | --spot-auto | --spot-policy POLICY]
                  [--retry | --no-retry | --retry-duration DURATION]
                  [-e KEY=VALUE] [--gpu SPEC] [--disk RANGE]
                  working_dir

Positional Arguments:
  working_dir

Options:
  --project NAME        The name of the project. Defaults to $DSTACK_PROJECT
  -h, --help [TYPE]     Show this help message and exit. TYPE is one of task,
                        dev-environment, service
  -f, --file FILE       The path to the run configuration file. Defaults to
                        WORKING_DIR/.dstack.yml
  -n, --name RUN_NAME   The name of the run. If not specified, a random name
                        is assigned
  -d, --detach          Do not poll logs and run status
  -y, --yes             Do not ask for plan confirmation
  --max-offers MAX_OFFERS
                        Number of offers to show in the run plan
  -e, --env KEY=VALUE   Environment variables
  --gpu SPEC            Request GPU for the run. The format is
                        NAME:COUNT:MEMORY (all parts are optional)
  --disk RANGE          Request the size range of disk for the run. Example
                        --disk 100GB...

Profile:
  --profile NAME        The name of the profile. Defaults to $DSTACK_PROFILE
  --max-price PRICE     The maximum price per hour, in dollars
  --max-duration DURATION
                        The maximum duration of the run
  -b, --backend NAME    The backends that will be tried for provisioning
  -r, --region NAME     The regions that will be tried for provisioning
  --instance-type NAME  The cloud-specific instance types that will be tried
                        for provisioning

Pools:
  --pool POOL_NAME      The name of the pool. If not set, the default pool
                        will be used
  --reuse               Reuse instance from pool
  --dont-destroy        Do not destroy instance after the run is finished
  --idle-duration IDLE_DURATION
                        Time to wait before destroying the idle instance
  --instance NAME       Reuse instance from pool with name NAME

Spot Policy:
  --spot                Consider only spot instances
  --on-demand           Consider only on-demand instances
  --spot-auto           Consider both spot and on-demand instances
  --spot-policy POLICY  One of spot, on-demand, auto

Retry Policy:
  --retry
  --no-retry
  --retry-duration DURATION
.gitignore

When running anything via CLI, dstack uses the exact version of code from your project directory.

If there are large files, consider creating a .gitignore file to exclude them for better performance.

dstack apply

This command applies a given configuration. If a resource does not exist, dstack apply creates the resource. If a resource exists, dstack apply updates the resource in-place or re-creates the resource if the update is not possible.

$ dstack apply --help
Usage: dstack apply [-h] [--project NAME] [-f FILE] [--force] [-y]

Options:
  -h, --help            Show this help message and exit
  --project NAME        The name of the project. Defaults to $DSTACK_PROJECT
  -f, --file FILE       The path to the configuration file. Defaults to
                        $PWD/.dstack.yml
  --force               Force apply when no changes detected
  -y, --yes             Do not ask for confirmation

NOTE:

The dstack apply command currently supports only gateway configurations. Support for other configuration types is coming soon.

dstack delete

This command deletes the resources defined by a given configuration.

$ dstack delete --help
Usage: dstack delete [-h] [--project NAME] [-f FILE] [-y]

Options:
  -h, --help            Show this help message and exit
  --project NAME        The name of the project. Defaults to $DSTACK_PROJECT
  -f, --file FILE       The path to the configuration file. Defaults to
                        $PWD/.dstack.yml
  -y, --yes             Do not ask for confirmation

NOTE:

The dstack delete command currently supports only gateway configurations. Support for other configuration types is coming soon.

dstack ps

This command shows the status of runs.

$ dstack ps --help
Usage: dstack ps [-h] [--project NAME] [-a] [-v] [-w]

Options:
  -h, --help      Show this help message and exit
  --project NAME  The name of the project. Defaults to $DSTACK_PROJECT
  -a, --all       Show all runs. By default, it only shows unfinished runs or
                  the last finished.
  -v, --verbose   Show more information about runs
  -w, --watch     Watch statuses of runs in realtime

dstack stop

This command stops run(s) within the current repository.

$ dstack stop --help
Usage: dstack stop [-h] [--project NAME] [-x] [-y] run_name

Positional Arguments:
  run_name

Options:
  -h, --help      Show this help message and exit
  --project NAME  The name of the project. Defaults to $DSTACK_PROJECT
  -x, --abort
  -y, --yes

dstack logs

This command shows the output of a given run within the current repository.

$ dstack logs --help
Usage: dstack logs [-h] [--project NAME] [-d] [-a]
                   [--ssh-identity SSH_PRIVATE_KEY] [--replica REPLICA]
                   [--job JOB]
                   run_name

Positional Arguments:
  run_name

Options:
  -h, --help            Show this help message and exit
  --project NAME        The name of the project. Defaults to $DSTACK_PROJECT
  -d, --diagnose
  -a, --attach          Set up an SSH tunnel, and print logs as they follow.
  --ssh-identity SSH_PRIVATE_KEY
                        The private SSH key path for SSH tunneling
  --replica REPLICA     The relica number. Defaults to 0.
  --job JOB             The job number inside the replica. Defaults to 0.

dstack config

Both the CLI and API need to be configured with the server address, user token, and project name via ~/.dstack/config.yml.

At startup, the server automatically configures CLI and API with the server address, user token, and the default project name (main). This configuration is stored via ~/.dstack/config.yml.

To use CLI and API on different machines or projects, use the dstack config command.

$ dstack config --help
Usage: dstack config [-h] [--project PROJECT] [--url URL] [--token TOKEN]
                     [--default] [--remove] [--no-default]

Options:
  -h, --help         Show this help message and exit
  --project PROJECT  The name of the project to configure
  --url URL          Server url
  --token TOKEN      User token
  --default          Set the project as default. It will be used when
                     --project is omitted in commands.
  --remove           Delete project configuration
  --no-default       Do not prompt to set the project as default

dstack pool

Pools allow for managing the lifecycle of instances and reusing them across runs. The default pool is created automatically.

dstack pool add

The dstack pool add command provisions a cloud instance and adds it to a pool. If no pool name is specified, the instance goes to the default pool.

$ dstack pool add --help
Usage: dstack pool add [-h] [-y] [--profile NAME] [--max-price PRICE]
                       [-b NAME] [-r NAME] [--instance-type NAME]
                       [--pool POOL_NAME] [--reuse] [--dont-destroy]
                       [--idle-duration IDLE_DURATION]
                       [--spot | --on-demand | --spot-auto | --spot-policy POLICY]
                       [--retry | --no-retry | --retry-duration DURATION]
                       [--cpu SPEC] [--memory SIZE] [--shared-memory SIZE]
                       [--gpu SPEC] [--disk SIZE]

Options:
  -h, --help            show this help message and exit
  -y, --yes             Don't ask for confirmation
  --pool POOL_NAME      The name of the pool. If not set, the default pool
                        will be used
  --reuse               Reuse instance from pool
  --dont-destroy        Do not destroy instance after the run is finished
  --idle-duration IDLE_DURATION
                        Time to wait before destroying the idle instance

Profile:
  --profile NAME        The name of the profile. Defaults to $DSTACK_PROFILE
  --max-price PRICE     The maximum price per hour, in dollars
  -b, --backend NAME    The backends that will be tried for provisioning
  -r, --region NAME     The regions that will be tried for provisioning
  --instance-type NAME  The cloud-specific instance types that will be tried
                        for provisioning

Spot Policy:
  --spot                Consider only spot instances
  --on-demand           Consider only on-demand instances
  --spot-auto           Consider both spot and on-demand instances
  --spot-policy POLICY  One of spot, on-demand, auto

Retry Policy:
  --retry
  --no-retry
  --retry-duration DURATION

Resources:
  --cpu SPEC            Request the CPU count. Default: 2..
  --memory SIZE         Request the size of RAM. The format is SIZE:MB|GB|TB.
                        Default: 8GB..
  --shared-memory SIZE  Request the size of Shared Memory. The format is
                        SIZE:MB|GB|TB.
  --gpu SPEC            Request GPU for the run. The format is
                        NAME:COUNT:MEMORY (all parts are optional)
  --disk SIZE           Request the size of disk for the run. Example --disk
                        100GB...
dstack pool add-ssh

The dstack pool add-ssh command adds an existing remote instance to a pool. If no pool name is specified, the instance goes to the default pool.

$ dstack pool add-ssh --help
Usage: dstack pool add-ssh [-h] -i SSH_PRIVATE_KEY [-p SSH_PORT]
                           [-l LOGIN_NAME] [--region REGION]
                           [--pool POOL_NAME] [--name INSTANCE_NAME]
                           [--network NETWORK]
                           destination

Positional Arguments:
  destination

Options:
  -h, --help            show this help message and exit
  -i SSH_PRIVATE_KEY    The private SSH key path for SSH
  -p SSH_PORT           SSH port to connect
  -l LOGIN_NAME         User to login
  --region REGION       Host region
  --pool POOL_NAME      Pool name
  --name INSTANCE_NAME  Set the name of the instance
  --network NETWORK     Network address for multinode setup. Format <ip
                        address>/<netmask>
dstack pool ps

The dstack pool ps command lists all active instances of a pool. If no pool name is specified, default pool instances are displayed.

$ dstack pool ps --help
Usage: dstack pool ps [-h] [--pool POOL_NAME] [-w]

Show instances in the pool

Options:
  -h, --help        show this help message and exit
  --pool POOL_NAME  The name of the pool. If not set, the default pool will be
                    used
  -w, --watch       Watch instances in realtime
dstack pool rm

The dstack pool rm command removes an instance from a pool. Cloud instances are terminated upon removal.

$ dstack pool rm --help
Usage: dstack pool rm [-h] [--pool POOL_NAME] [--force] [-y] instance_name

Positional Arguments:
  instance_name     The name of the instance

Options:
  -h, --help        show this help message and exit
  --pool POOL_NAME  The name of the pool. If not set, the default pool will be
                    used
  --force           The name of the instance
  -y, --yes         Don't ask for confirmation
dstack pool create

The dstack pool create command creates a new pool.

$ dstack pool create --help
Usage: dstack pool create [-h] -n POOL_NAME

Options:
  -h, --help            show this help message and exit
  -n, --name POOL_NAME  The name of the pool
dstack pool list

The dstack pool list command lists all existing pools.

$ dstack pool delete --help
Usage: dstack pool delete [-h] -n POOL_NAME

Options:
  -h, --help            show this help message and exit
  -n, --name POOL_NAME  The name of the pool
dstack pool set-default

The dstack pool set-default command sets the project's default pool.

$ dstack pool set-default --help
Usage: dstack pool set-default [-h] --pool POOL_NAME

Options:
  -h, --help        show this help message and exit
  --pool POOL_NAME  The name of the pool
dstack pool delete

The dstack pool delete command deletes a specified pool.

$ dstack pool delete --help
Usage: dstack pool delete [-h] -n POOL_NAME

Options:
  -h, --help            show this help message and exit
  -n, --name POOL_NAME  The name of the pool

dstack gateway

A gateway is required for running services. It handles ingress traffic, authorization, domain mapping, model mapping for the OpenAI-compatible endpoint, and so on.

dstack gateway list

The dstack gateway list command displays the names and addresses of the gateways configured in the project.

$ dstack gateway list --help
Usage: dstack gateway list [-h] [-v]

Options:
  -h, --help     show this help message and exit
  -v, --verbose  Show more information
dstack gateway create

The dstack gateway create command creates a new gateway instance in the project.

$ dstack gateway create --help
Usage: dstack gateway create [-h] --backend {aws,azure,gcp,kubernetes}
                             --region REGION [--set-default] [--name NAME]
                             --domain DOMAIN

Options:
  -h, --help            show this help message and exit
  --backend {aws,azure,gcp,kubernetes}
  --region REGION
  --set-default         Set as default gateway for the project
  --name NAME           Set a custom name for the gateway
  --domain DOMAIN       Set the domain for the gateway
dstack gateway delete

The dstack gateway delete command deletes the specified gateway.

$ dstack gateway delete --help
Usage: dstack gateway delete [-h] [-y] name

Positional Arguments:
  name        The name of the gateway

Options:
  -h, --help  show this help message and exit
  -y, --yes   Don't ask for confirmation
dstack gateway update

The dstack gateway update command updates the specified gateway.

$ dstack gateway update --help
Usage: dstack gateway update [-h] [--set-default] [--domain DOMAIN] name

Positional Arguments:
  name             The name of the gateway

Options:
  -h, --help       show this help message and exit
  --set-default    Set it the default gateway for the project
  --domain DOMAIN  Set the domain for the gateway

Environment variables

Name Description Default
DSTACK_CLI_LOG_LEVEL Configures CLI logging level INFO
DSTACK_PROFILE Has the same effect as --profile None
DSTACK_PROJECT Has the same effect as --project None
DSTACK_DEFAULT_CREDS_DISABLED Disables default credentials detection if set None
DSTACK_LOCAL_BACKEND_ENABLED Enables local backend for debug if set None
DSTACK_RUNNER_VERSION Sets exact runner version for debug latest
DSTACK_SERVER_ADMIN_TOKEN Has the same effect as --token None
DSTACK_SERVER_DIR Sets path to store data and server configs ~/.dstack/server
DSTACK_SERVER_HOST Has the same effect as --host 127.0.0.1
DSTACK_SERVER_LOG_LEVEL Has the same effect as --log-level INFO
DSTACK_SERVER_LOG_FORMAT Sets format of log output. Can be rich, standard, json. rich
DSTACK_SERVER_PORT Has the same effect as --port 3000
DSTACK_SERVER_ROOT_LOG_LEVEL Sets root logger log level ERROR
DSTACK_SERVER_UVICORN_LOG_LEVEL Sets uvicorn logger log level ERROR