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
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 allows publishing services at a custom domain with HTTPS.
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 toINFO.DSTACK_SERVER_LOG_LEVEL– (Optional) Has the same effect as--log-level. Defaults toINFO.DSTACK_SERVER_HOST– (Optional) Has the same effect as--host. Defaults to127.0.0.1.DSTACK_SERVER_PORT– (Optional) Has the same effect as--port. Defaults to3000.DSTACK_SERVER_ADMIN_TOKEN– (Optional) Has the same effect as--token. Defaults toNone.DSTACK_DATABASE_URL– (Optional) The database URL to use instead of default SQLite. Currentlydstacksupports Postgres. Example:postgresql+asyncpg://myuser:mypassword@localhost:5432/mydatabase. Defaults toNone.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 toNone.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 toERROR.DSTACK_SERVER_LOG_FORMAT– (Optional) Sets format of log output. Can berich,standard,json. Defaults torich.DSTACK_SERVER_UVICORN_LOG_LEVEL– (Optional) Sets uvicorn logger log level. Defaults toERROR.DSTACK_PROFILE– (Optional) Has the same effect as--profile. Defaults toNone.DSTACK_PROJECT– (Optional) Has the same effect as--project. Defaults toNone.DSTACK_RUNNER_VERSION– (Optional) Sets exact runner version for debug. Defaults tolatest.DSTACK_DEFAULT_CREDS_DISABLED– (Optional) Disables default credentials detection if set. Defaults toNone.DSTACK_LOCAL_BACKEND_ENABLED– (Optional) Enables local backend for debug if set. Defaults toNone.