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 WARNING.
  --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] [--pool POOL_NAME] [--reuse]
                  [--idle-duration IDLE_DURATION] [--instance NAME]
                  [--profile NAME] [--max-price PRICE]
                  [--max-duration DURATION] [-b NAME]
                  [--spot | --on-demand | --spot-auto | --spot-policy POLICY]
                  [--retry | --no-retry | --retry-limit 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
  --pool POOL_NAME      The name of the pool. If not set, the default pool
                        will be used
  --reuse               Reuse instance from pool
  --idle-duration IDLE_DURATION
                        Idle time before instance termination
  --instance NAME       Reuse instance from pool with name NAME
  -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
  -b, --backend NAME    The backends 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-limit 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 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]
                   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

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 adds an instance 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] [--pool POOL_NAME] [-y] [--remote]
                       [--remote-host REMOTE_HOST] [--remote-port REMOTE_PORT]
                       [--name INSTANCE_NAME] [--idle-duration IDLE_DURATION]
                       [--profile NAME] [--max-price PRICE]
                       [--max-duration DURATION] [-b NAME]
                       [--spot | --on-demand | --spot-auto | --spot-policy POLICY]
                       [--retry | --no-retry | --retry-limit DURATION]
                       [--cpu SPEC] [--memory SIZE] [--shared-memory SIZE]
                       [--gpu SPEC] [--disk SIZE]

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
  -y, --yes             Don't ask for confirmation
  --remote              Add remote runner as an instance
  --remote-host REMOTE_HOST
                        Remote runner host
  --remote-port REMOTE_PORT
                        Remote runner port
  --name INSTANCE_NAME  Set the name of the instance
  --idle-duration IDLE_DURATION
                        Idle duration

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
  -b, --backend NAME    The backends 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-limit 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 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 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 lists all existing pools.

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

Options:
  -h, --help            show this help message and exit
  -n, --name POOL_NAME  The name of the pool
  -f, --force FORCE     Force remove
dstack pool delete

The dstack pool delete command deletes a specified pool.

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

Options:
  -h, --help            show this help message and exit
  -n, --name POOL_NAME  The name of the pool
  -f, --force FORCE     Force remove

dstack gateway

A gateway is required for running services. It handles ingress traffic, authentication, 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 CRITICAL
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 WARNING
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