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

Options:
  -h, --help            show this help message and exit
  -n, --name 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`