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] [-y] [-n]
                     [--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.
  -y, --yes             Don't ask for confirmation (e.g. update the config)
  -n, --no              Don't ask for confirmation (e.g. do not update the
                        config)
  --token TOKEN         The admin user token

dstack init

This command must be called inside a folder before you can run dstack apply.

Git credentials

If the current folder is a remote Git repository, dstack init ensures that dstack can access it. By default, the command uses the remote repo's default Git credentials. These can be overridden with --git-identity (private SSH key) or --token (OAuth token).

$ 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

User SSH key

By default, dstack uses its own SSH key to access instances (~/.dstack/ssh/id_rsa). It is possible to override this key via the --ssh-identity argument.

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 [--project NAME] [-h [TYPE]] [-f FILE] [-y] [--force] [-d]

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

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).

$ 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 attach

This command attaches to a given run. It establishes the SSH tunnel, forwards ports, and shows real-time run logs.

$ dstack attach --help
Usage: dstack attach [-h] [--project NAME] [--ssh-identity SSH_PRIVATE_KEY]
                     [--logs] [--host HOST] [-p MAPPING] [--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
  --ssh-identity SSH_PRIVATE_KEY
                        The private SSH key path for SSH tunneling
  --logs                Print run logs as they follow
  --host HOST           Local address to bind. Defaults to localhost.
  -p, --port MAPPING    Port mapping overrides
  --replica REPLICA     The relica number. Defaults to 0.
  --job JOB             The job number inside the replica. Defaults to 0.

dstack logs

This command shows the output of a given run.

$ 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        Show run diagnostic logs
  -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 stats

This command shows run hardware metrics such as CPU, memory, and GPU utilization.

$ dstack stats --help
Usage: dstack stats [-h] [--project NAME] [-w] 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
  -w, --watch     Watch run stats in realtime

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] [-y]
                     [--remove] [-n]

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
  -y, --yes          Don't ask for confirmation (e.g. update the config)
  --remove           Delete project configuration
  -n, --no           Don't ask for confirmation (e.g. do not update the
                     config)

dstack fleet

Fleets enable efficient provisioning and management of clusters and instances.

dstack fleet list

The dstack fleet list command displays fleets and instances.

$ dstack fleet list --help
Usage: dstack fleet list [-h] [-w] [-v]

Options:
  -h, --help     show this help message and exit
  -w, --watch    Update listing in realtime
  -v, --verbose  Show more information
dstack fleet delete

The dstack fleet delete deletes fleets and instances. Cloud instances are terminated upon deletion.

$ dstack fleet delete --help
Usage: dstack fleet delete [-h] [-i INSTANCE_NUM] [-y] name

Positional Arguments:
  name                  The name of the fleet

Options:
  -h, --help            show this help message and exit
  -i, --instance INSTANCE_NUM
                        The instances to delete
  -y, --yes             Don't ask for confirmation

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] [-w] [-v]

Options:
  -h, --help     show this help message and exit
  -w, --watch    Update listing in realtime
  -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

dstack volume

The volumes commands.

dstack volume list

The dstack volume list command lists volumes.

$ dstack volume list --help
Usage: dstack volume list [-h] [-w] [-v]

Options:
  -h, --help     show this help message and exit
  -w, --watch    Update listing in realtime
  -v, --verbose  Show more information
dstack volume delete

The dstack volume delete command deletes volumes.

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

Positional Arguments:
  name        The name of the volume

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

dstack run

This command runs a given configuration.

Deprecation

dstack run is deprecated in favor of dstack apply.

$ dstack run . --help
Usage: dstack run [--project NAME] [-h [TYPE]] [-f FILE] [-y] [-n RUN_NAME]
                  [--max-offers MAX_OFFERS] [-e KEY[=VALUE]] [--gpu SPEC]
                  [--disk RANGE] [--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]
                  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 configuration file. Defaults to
                        $PWD/.dstack.yml
  -y, --yes             Do not ask for confirmation
  -n, --name RUN_NAME   The name of the run. If not specified, a random name
                        is assigned
  --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 pool

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

Deprecation

Pools are deprecated in favor of fleets and will be removed in 0.19.0.

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 list --help
Usage: dstack pool list [-h] [-v VERBOSE]

List available pools

Options:
  -h, --help            show this help message and exit
  -v, --verbose VERBOSE
                        Show more information
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

Environment variables

  • DSTACK_CLI_LOG_LEVEL – (Optional) Configures CLI logging level. Defaults to INFO.
  • DSTACK_SERVER_LOG_LEVEL – (Optional) Has the same effect as --log-level. Defaults to INFO.
  • DSTACK_SERVER_HOST – (Optional) Has the same effect as --host. Defaults to 127.0.0.1.
  • DSTACK_SERVER_PORT – (Optional) Has the same effect as --port. Defaults to 3000.
  • DSTACK_SERVER_ADMIN_TOKEN – (Optional) Has the same effect as --token. Defaults to None.
  • DSTACK_DATABASE_URL – (Optional) The database URL to use instead of default SQLite. Currently dstack supports Postgres. Example: postgresql+asyncpg://myuser:mypassword@localhost:5432/mydatabase. Defaults to None.
  • DSTACK_SERVER_CLOUDWATCH_LOG_GROUP – (Optional) The CloudWatch Logs group for workloads logs. If not set, the default file-based log storage is used.
  • DSTACK_SERVER_CLOUDWATCH_LOG_REGION — (Optional) The CloudWatch Logs region. Defaults to None.
  • DSTACK_DEFAULT_SERVICE_CLIENT_MAX_BODY_SIZE – (Optional) Request body size limit for services, in bytes. Defaults to 64 MiB.
  • DSTACK_FORBID_SERVICES_WITHOUT_GATEWAY - (Optional) Forbids registering new services without a gateway if set to any value.
  • DSTACK_SERVER_DIR – (Optional) Sets path to store data and server configs. Defaults to ~/.dstack/server.
Internal environment variables
  • DSTACK_SERVER_ROOT_LOG_LEVEL – (Optional) Sets root logger log level. Defaults to ERROR.
  • DSTACK_SERVER_LOG_FORMAT – (Optional) Sets format of log output. Can be rich, standard, json.. Defaults to rich.
  • DSTACK_SERVER_UVICORN_LOG_LEVEL – (Optional) Sets uvicorn logger log level. Defaults to ERROR.
  • DSTACK_PROFILE – (Optional) Has the same effect as --profile. Defaults to None.
  • DSTACK_PROJECT – (Optional) Has the same effect as --project. Defaults to None.
  • DSTACK_RUNNER_VERSION – (Optional) Sets exact runner version for debug. Defaults to latest.
  • DSTACK_DEFAULT_CREDS_DISABLED – (Optional) Disables default credentials detection if set. Defaults to None.
  • DSTACK_LOCAL_BACKEND_ENABLED – (Optional) Enables local backend for debug if set. Defaults to None.