Dev environments¶

A dev environment lets you provision a remote machine with your code, dependencies, and resources, and access it with your desktop IDE.

Dev environments are perfect when you need to run code interactively.

Define a configuration¶

First, create a YAML file in your project repo. Its name must end with .dstack.yml (e.g. .dstack.yml or dev.dstack.yml are both acceptable).

type: dev-environment
# The name is optional, if not specified, generated randomly
name: vscode

python: "3.11"
# Uncomment to use a custom Docker image
#image: dstackai/base:py3.13-0.6-cuda-12.1
ide: vscode

# Uncomment to leverage spot instances
#spot_policy: auto

resources:
  gpu: 24GB

If you don't specify your Docker image, dstack uses the base image (pre-configured with Python, Conda, and essential CUDA drivers).

Reference

See .dstack.yml for all the options supported by dev environments, along with multiple examples.

Run a configuration¶

To run a configuration, use the dstack apply command.

$ dstack apply -f examples/.dstack.yml

 #  BACKEND  REGION    RESOURCES                SPOT  PRICE
 1  runpod   CA-MTL-1  9xCPU, 48GB, A5000:24GB  yes   $0.11
 2  runpod   EU-SE-1   9xCPU, 43GB, A5000:24GB  yes   $0.11
 3  gcp      us-west4  4xCPU, 16GB, L4:24GB     yes   $0.214516

Submit the run vscode? [y/n]: y

Launching `vscode`...
---> 100%

To open in VS Code Desktop, use this link:
  vscode://vscode-remote/ssh-remote+vscode/workflow

dstack apply automatically uploads the code from the current repo, including your local uncommitted changes. To avoid uploading large files, ensure they are listed in .gitignore.

VS Code¶

To open the dev environment in your desktop IDE, use the link from the output (such as vscode://vscode-remote/ssh-remote+fast-moth-1/workflow).

SSH¶

Alternatively, while the CLI is attached to the run, you can connect to the dev environment via SSH:

$ ssh fast-moth-1

Manage runs¶

List runs¶

The dstack ps command lists all running jobs and their statuses. Use --watch (or -w) to monitor the live status of runs.

Stop a run¶

Once the run exceeds the max_duration, or when you use dstack stop, the dev environment is stopped. Use --abort or -x to stop the run abruptly.

Manage fleets¶

By default, dstack apply reuses idle instances from one of the existing fleets, or creates a new fleet through backends.

Idle duration

To ensure the created fleets are deleted automatically, set termination_idle_time. By default, it's set to 5min.

Creation policy

To ensure dstack apply always reuses an existing fleet and doesn't create a new one, pass --reuse to dstack apply (or set creation_policy to reuse in the task configuration). The default policy is reuse_or_create.

What's next?¶

Read about dev environments, tasks, and services
See fleets on how to manage fleets

Reference

See .dstack.yml for all the options supported by dev environments, along with multiple examples.