dstackai · peterschmidt85 · Dec 4, 2025 · Dec 3, 2025
diff --git a/docs/docs/concepts/backends.md b/docs/docs/concepts/backends.md
@@ -1,18 +1,16 @@
 # Backends
 
-Backends allow `dstack` to manage compute across various environments.
-They can be configured via `~/.dstack/server/config.yml` or through the [project settings page](../concepts/projects.md#backends) in the UI.
+Backends allow `dstack` to provision fleets across cloud providers or Kubernetes clusters.
 
-`dstack` supports three types of backends: 
+`dstack` supports two types of backends: 
 
   * [VM-based](#vm-based) – use `dstack`'s native integration with cloud providers to provision VMs, manage clusters, and orchestrate container-based runs.  
   * [Container-based](#container-based) – use either `dstack`'s native integration with cloud providers or Kubernetes to orchestrate container-based runs; provisioning in this case is delegated to the cloud provider or Kubernetes.  
-  * [On-prem](#on-prem) – use `dstack`'s native support for on-prem servers without needing Kubernetes.  
 
-!!! info "dstack Sky"
-    If you're using [dstack Sky](https://sky.dstack.ai), backend configuration is optional. dstack Sky lets you use pre-configured backends to access GPU marketplace.
+??? info "SSH fleets"
+    When using `dstack` with on-prem servers, backend configuration isn’t required. Simply create [SSH fleets](../concepts/fleets.md#ssh-fleets) once the server is up.
 
-See the examples of backend configuration below.
+Backends can be configured via `~/.dstack/server/config.yml` or through the [project settings page](../concepts/projects.md#backends) in the UI. See the examples of backend configuration below.
 
 ## VM-based
 
@@ -1154,16 +1152,6 @@ projects:
 
 Also, the `vastai` backend supports on-demand instances only. Spot instance support coming soon.
 
-## On-prem
-
-In on-prem environments, the [Kubernetes](#kubernetes) backend can be used if a Kubernetes cluster is already set up and configured.  
-However, often [SSH fleets](../concepts/fleets.md#ssh-fleets) are a simpler and lighter alternative.
-
-### SSH fleets
-
-SSH fleets require no backend configuration. 
-All you need to do is [provide hostnames and SSH credentials](../concepts/fleets.md#ssh-fleets), and `dstack` sets up a fleet that can orchestrate container-based runs on your servers.
-
 SSH fleets support the same features as [VM-based](#vm-based) backends.
 
 !!! info "What's next"

diff --git a/docs/docs/concepts/dev-environments.md b/docs/docs/concepts/dev-environments.md
@@ -2,9 +2,12 @@
 
 A dev environment lets you provision an instance and access it with your desktop IDE.
 
+??? info "Prerequisites"
+    Before running a dev environment, make sure you’ve [installed](../installation/index.md) the server and CLI, and created a [fleet](fleets.md).
+
 ## Apply a configuration
 
-First, define a dev environment configuration as a YAML file in your project folder.
+First, define a dev environment configuration as a YAML file.
 The filename must end with `.dstack.yml` (e.g. `.dstack.yml` or `dev.dstack.yml` are both acceptable).
 
 <div editor-title="examples/.dstack.yml"> 

diff --git a/docs/docs/concepts/fleets.md b/docs/docs/concepts/fleets.md
@@ -4,27 +4,31 @@ Fleets act both as pools of instances and as templates for how those instances a
 
 `dstack` supports two kinds of fleets: 
 
-* [Backend fleets](#backend-fleets) – dynamically provisioned through configured backends; they are supported with any type of backends: [VM-based](backends.md#vm-based) and [container-based](backends.md#container-based) (incl. [`kubernetes`](backends.md#kubernetes))
+* [Backend fleets](#backend-fleets) – dynamically provisioned through configured backends; they are supported with any type of backends: [VM-based](backends.md#vm-based) and [container-based](backends.md#container-based) (incl. [Kubernetes](backends.md#kubernetes))
 * [SSH fleets](#ssh-fleets) – created using on-prem servers; do not require backends
 
-When you run `dstack apply` to start a dev environment, task, or service, `dstack` will reuse idle instances from an existing fleet whenever available.
+When you submit a dev environment, task, or service, `dstack` reuses idle instances or provisions new ones based on the fleet configuration. 
+
+> You must create a fleet before submitting runs.
 
 ## Backend fleets
 
-If you configured [backends](backends.md), `dstack` can provision fleets on the fly.
-However, it’s recommended to define fleets explicitly.
+Backend fleets allow provisioning compute across cloud providers or Kubernetes clusters. 
 
-### Apply a configuration
+??? info "Prerequisites"
+    Before creating a backend fleet, make sure to configure the corresponding [backends](backends.md).
+
+### Apply the configuration
 
-To create a backend fleet, define a configuration as a YAML file in your project directory. The file must have a
+To create a backend fleet, define a configuration as a YAML file. The file must have a
 `.dstack.yml` extension (e.g. `.dstack.yml` or `fleet.dstack.yml`).
 
-<div editor-title="examples/misc/fleets/.dstack.yml">
+<div editor-title="fleet.dstack.yml">
 
     ```yaml
     type: fleet
     # The name is optional, if not specified, generated randomly
-    name: default-fleet
+    name: default
 
     # Can be a range or a fixed number
     # Allow to provision of up to 2 instances
@@ -48,7 +52,7 @@ To create or update the fleet, pass the fleet configuration to [`dstack apply`](
 <div class="termy">
 
 ```shell
-$ dstack apply -f examples/misc/fleets/.dstack.yml
+$ dstack apply -f fleet.dstack.yml
 
 Provisioning...
 ---> 100%
@@ -59,18 +63,15 @@ Provisioning...
 
 </div>
 
-`dstack` always keeps the minimum number of nodes provisioned. Additional instances, up to the maximum limit, are provisioned on demand.
-
-!!! info "Container-based backends"
-    For [container-based](backends.md#container-based) backends  (such as `kubernetes`, `runpod`, etc), `nodes` must be defined as a range starting with `0`. In these cases, instances are provisioned on demand as needed.
+If `nodes` is a range that starts above `0`, `dstack` pre-creates the initial number of instances up front, while any additional ones are created on demand. 
 
-    <!-- TODO: Ensure the user sees the error or warning otherwise -->
+> Setting the `nodes` range to start above `0` is supported only for [VM-based backends](backends.md#vm-based).
 
 ??? info "Target number of nodes"
 
     If `nodes` is defined as a range, you can start with more than the minimum number of instances by using the `target` parameter when creating the fleet.
 
-    <div editor-title=".dstack.yml"> 
+    <div editor-title="fleet.dstack.yml"> 
 
     ```yaml
     type: fleet

diff --git a/docs/docs/concepts/services.md b/docs/docs/concepts/services.md
@@ -2,6 +2,9 @@
 
 Services allow you to deploy models or web apps as secure and scalable endpoints.
 
+??? info "Prerequisites"
+    Before running a service, make sure you’ve [installed](../installation/index.md) the server and CLI, and created a [fleet](fleets.md).
+
 ## Apply a configuration
 
 First, define a service configuration as a YAML file in your project folder.

diff --git a/docs/docs/concepts/tasks.md b/docs/docs/concepts/tasks.md
@@ -1,11 +1,13 @@
 # Tasks
 
-A task allows you to run arbitrary commands on one or more nodes.
-They are best suited for jobs like training or batch processing.
+A task allows you to run arbitrary commands on one or more nodes. They are best suited for jobs like training or batch processing.
+
+??? info "Prerequisites"
+    Before running a task, make sure you’ve [installed](../installation/index.md) the server and CLI, and created a [fleet](fleets.md).
 
 ## Apply a configuration
 
-First, define a task configuration as a YAML file in your project folder.
+First, define a task configuration as a YAML file.
 The filename must end with `.dstack.yml` (e.g. `.dstack.yml` or `dev.dstack.yml` are both acceptable).
 
 [//]: # (TODO: Make tabs - single machine & distributed tasks & web app)

diff --git a/docs/docs/installation/index.md b/docs/docs/installation/index.md
@@ -8,11 +8,7 @@
 
 ### Configure backends
 
-To orchestrate compute across cloud providers or existing Kubernetes clusters, you need to configure backends.
-
-Backends can be set up in `~/.dstack/server/config.yml` or through the [project settings page](../concepts/projects.md#backends) in the UI.
-
-For more details, see [Backends](../concepts/backends.md).
+To orchestrate compute across cloud providers or Kubernetes clusters, you need to configure [backends](../concepts/backends.md).
 
 ??? info "SSH fleets"
     When using `dstack` with on-prem servers, backend configuration isn’t required. Simply create [SSH fleets](../concepts/fleets.md#ssh-fleets) once the server is up.
@@ -79,8 +75,7 @@ The server can run on your laptop or any environment with access to the cloud an
 To verify that backends are properly configured, use the [`dstack offer`](../reference/cli/dstack/offer.md#list-gpu-offers) command to list available GPU offers.
 
 !!! info "Server deployment"
-    For more details on server deployment options, see the
-    [Server deployment](../guides/server-deployment.md) guide.
+    For more details on server deployment options, see the [Server deployment](../guides/server-deployment.md) guide.
 
 ## Set up the CLI
 
@@ -206,5 +201,5 @@ This configuration is stored in `~/.dstack/config.yml`.
     1. Follow [Quickstart](../quickstart.md)
     2. See [Backends](../concepts/backends.md)
     3. Check the [server deployment](../guides/server-deployment.md) guide
-    4. Browse [examples](/examples)
+    4. Browse [examples](../../examples.md)
     5. Join the community via [Discord](https://discord.gg/u8SmfwPpMd)