Deploying to gh-pages from @ dstackai/dstack@43f2221 🚀

Author: peterschmidt85

.well-known/skills/dstack/SKILL.md

@@ -148,6 +148,14 @@ If background attach fails in the sandbox (permissions writing `~/.dstack` or `~
 
 **"Connect to" or "open" a dev environment:** If a dev environment is already running, use `dstack attach <run name> --logs` (agent runs it in the background by default) to surface the IDE URL (`cursor://`, `vscode://`, etc.) and SSH alias. If sandboxed attach fails, request escalation or ask the user to run attach locally and share the link.
 
+### Distributed tasks and multi-replica services
+
+Unless you use **Distributed tasks** (see `### 2. Tasks`) or **Multi-replica services** (see `### 3. Services`), both tasks and services run on a single node. That's why `dstack logs <run name>`, `dstack attach <run name>`, and `ssh <run name>` default to the first replica/job.
+
+- In a distributed task, each node runs its own job, numbered from 0 in order across node groups. Target a node via `dstack logs <run name> --job 1` or `dstack attach <run name> --job 1`.
+- In a multi-replica service, replicas are numbered from 0 in order across replica groups. Target a replica via `dstack logs <run name> --replica 1` or `dstack attach <run name> --replica 1`.
+- Attaching with a non-zero `--job` or `--replica` creates the SSH alias `ssh <run name>-<job num>-<replica num>`.
+
 ## Configuration types
 
 `dstack` supports run configurations (dev environments, tasks, and services) and infrastructure configurations (fleets, volumes, and gateways). Configuration files can be named `<name>.dstack.yml` or simply `.dstack.yml`.
@@ -222,7 +230,7 @@ resources:
 
 **Port forwarding:** When you specify `ports`, `dstack apply` forwards them to `localhost` while attached. Use `dstack attach <run name>` to reconnect and restore port forwarding. The run name becomes an SSH alias (e.g., `ssh <run name>`) for direct access.
 
-**Distributed training:** Multi-node tasks are supported (e.g., via `nodes`) and require fleets that support inter-node communication (see `placement: cluster` in fleets).
+**Distributed tasks:** Set `nodes` to run a task across multiple nodes, or use `groups` to define node groups, each with its own `nodes` count, `resources`, `commands`, and `ports` (`groups` and top-level `nodes` are mutually exclusive). Requires a fleet that supports inter-node communication (see `placement: cluster` in fleets).
 
 [Concept documentation](https://dstack.ai/docs/concepts/tasks.md) | [Configuration reference](https://dstack.ai/docs/reference/dstack.yml/task.md)
 
@@ -262,6 +270,8 @@ resources:
     -d '{"model":"<model name>","messages":[{"role":"user","content":"Hello"}],"max_tokens":64}'
   ```
 
+**Multi-replica services:** Set `replicas` to run multiple replicas, or use `groups` to define replica groups, each with its own `replicas` count, `resources`, and `commands` (`groups` and top-level `replicas` are mutually exclusive). If replicas require an interconnect (e.g., PD disaggregation), the service must run on a fleet with `placement: cluster`.
+
 [Concept documentation](https://dstack.ai/docs/concepts/services.md) | [Configuration reference](https://dstack.ai/docs/reference/dstack.yml/service.md)
 
 ### 4. Fleets

SKILL.md

@@ -148,6 +148,14 @@ If background attach fails in the sandbox (permissions writing `~/.dstack` or `~
 
 **"Connect to" or "open" a dev environment:** If a dev environment is already running, use `dstack attach <run name> --logs` (agent runs it in the background by default) to surface the IDE URL (`cursor://`, `vscode://`, etc.) and SSH alias. If sandboxed attach fails, request escalation or ask the user to run attach locally and share the link.
 
+### Distributed tasks and multi-replica services
+
+Unless you use **Distributed tasks** (see `### 2. Tasks`) or **Multi-replica services** (see `### 3. Services`), both tasks and services run on a single node. That's why `dstack logs <run name>`, `dstack attach <run name>`, and `ssh <run name>` default to the first replica/job.
+
+- In a distributed task, each node runs its own job, numbered from 0 in order across node groups. Target a node via `dstack logs <run name> --job 1` or `dstack attach <run name> --job 1`.
+- In a multi-replica service, replicas are numbered from 0 in order across replica groups. Target a replica via `dstack logs <run name> --replica 1` or `dstack attach <run name> --replica 1`.
+- Attaching with a non-zero `--job` or `--replica` creates the SSH alias `ssh <run name>-<job num>-<replica num>`.
+
 ## Configuration types
 
 `dstack` supports run configurations (dev environments, tasks, and services) and infrastructure configurations (fleets, volumes, and gateways). Configuration files can be named `<name>.dstack.yml` or simply `.dstack.yml`.
@@ -222,7 +230,7 @@ resources:
 
 **Port forwarding:** When you specify `ports`, `dstack apply` forwards them to `localhost` while attached. Use `dstack attach <run name>` to reconnect and restore port forwarding. The run name becomes an SSH alias (e.g., `ssh <run name>`) for direct access.
 
-**Distributed training:** Multi-node tasks are supported (e.g., via `nodes`) and require fleets that support inter-node communication (see `placement: cluster` in fleets).
+**Distributed tasks:** Set `nodes` to run a task across multiple nodes, or use `groups` to define node groups, each with its own `nodes` count, `resources`, `commands`, and `ports` (`groups` and top-level `nodes` are mutually exclusive). Requires a fleet that supports inter-node communication (see `placement: cluster` in fleets).
 
 [Concept documentation](https://dstack.ai/docs/concepts/tasks.md) | [Configuration reference](https://dstack.ai/docs/reference/dstack.yml/task.md)
 
@@ -262,6 +270,8 @@ resources:
     -d '{"model":"<model name>","messages":[{"role":"user","content":"Hello"}],"max_tokens":64}'
   ```
 
+**Multi-replica services:** Set `replicas` to run multiple replicas, or use `groups` to define replica groups, each with its own `replicas` count, `resources`, and `commands` (`groups` and top-level `replicas` are mutually exclusive). If replicas require an interconnect (e.g., PD disaggregation), the service must run on a fleet with `placement: cluster`.
+
 [Concept documentation](https://dstack.ai/docs/concepts/services.md) | [Configuration reference](https://dstack.ai/docs/reference/dstack.yml/service.md)
 
 ### 4. Fleets

docs/concepts/presets.md

@@ -362,7 +362,6 @@ At the same time, it's recommended to create presets using your own agent — ei
 ## Limitations
 
 * Currently, the agent doesn't upload compiled binaries anywhere; patches compile at runtime
-* Doesn't support PD disaggregation (coming soon)
 * The registry doesn't support public presets (coming soon)
 * Doesn't support ranges for `concurrency`
 

docs/concepts/presets/index.html

@@ -5694,7 +5694,6 @@ <h2 id="protips">Protips<a class="headerlink" href="#protips" title="Permanent l
 <h2 id="limitations">Limitations<a class="headerlink" href="#limitations" title="Permanent link">&para;</a></h2>
 <ul>
 <li>Currently, the agent doesn't upload compiled binaries anywhere; patches compile at runtime</li>
-<li>Doesn't support PD disaggregation (coming soon)</li>
 <li>The registry doesn't support public presets (coming soon)</li>
 <li>Doesn't support ranges for <code>concurrency</code></li>
 </ul>

docs/index.html

@@ -5053,8 +5053,8 @@ <h2 id="how-does-it-work">How does it work?<a class="headerlink" href="#how-does
      dstackai/static-assets repo. The files are self-contained (embedded fonts + logos);
      the pair swaps with the docs theme via .arch-svg in
      mkdocs/assets/stylesheets/cloudscape-docs.css. -->
-<p><img class="arch-svg arch-svg--light" src="https://dstack.ai/static-assets/static-assets/images/dstack-architecture-diagram.svg" alt="dstack architecture: an orchestration layer between AI frameworks and models on top, and GPU clouds, Kubernetes, on-prem clusters, and hardware below.">
-<img class="arch-svg arch-svg--dark" src="https://dstack.ai/static-assets/static-assets/images/dstack-architecture-diagram-dark.svg" alt="dstack architecture: an orchestration layer between AI frameworks and models on top, and GPU clouds, Kubernetes, on-prem clusters, and hardware below."></p>
+<p><img class="arch-svg arch-svg--light" src="https://dstack.ai/static-assets/static-assets/images/dstack-architecture-diagram.svg" alt="dstack architecture: an orchestration layer between AI frameworks and models on top, and GPU clouds, Kubernetes, VMs, bare-metal, and hardware below.">
+<img class="arch-svg arch-svg--dark" src="https://dstack.ai/static-assets/static-assets/images/dstack-architecture-diagram-dark.svg" alt="dstack architecture: an orchestration layer between AI frameworks and models on top, and GPU clouds, Kubernetes, VMs, bare-metal, and hardware below."></p>
 <h3 id="set-up-the-server">Set up the server<a class="headerlink" href="#set-up-the-server" title="Permanent link">&para;</a></h3>
 <blockquote>
 <p>Before using <code>dstack</code>, ensure you've <a href="installation/">installed</a> the server, or signed up for <a href="https://sky.dstack.ai">dstack Sky</a>.</p>

docs/index.md

@@ -19,8 +19,8 @@ It streamlines development, training, and inference, and is compatible with any
      dstackai/static-assets repo. The files are self-contained (embedded fonts + logos);
      the pair swaps with the docs theme via .arch-svg in
      mkdocs/assets/stylesheets/cloudscape-docs.css. -->
-<img class="arch-svg arch-svg--light" src="https://dstack.ai/static-assets/static-assets/images/dstack-architecture-diagram.svg" alt="dstack architecture: an orchestration layer between AI frameworks and models on top, and GPU clouds, Kubernetes, on-prem clusters, and hardware below.">
-<img class="arch-svg arch-svg--dark" src="https://dstack.ai/static-assets/static-assets/images/dstack-architecture-diagram-dark.svg" alt="dstack architecture: an orchestration layer between AI frameworks and models on top, and GPU clouds, Kubernetes, on-prem clusters, and hardware below.">
+<img class="arch-svg arch-svg--light" src="https://dstack.ai/static-assets/static-assets/images/dstack-architecture-diagram.svg" alt="dstack architecture: an orchestration layer between AI frameworks and models on top, and GPU clouds, Kubernetes, VMs, bare-metal, and hardware below.">
+<img class="arch-svg arch-svg--dark" src="https://dstack.ai/static-assets/static-assets/images/dstack-architecture-diagram-dark.svg" alt="dstack architecture: an orchestration layer between AI frameworks and models on top, and GPU clouds, Kubernetes, VMs, bare-metal, and hardware below.">
 
 ### Set up the server
 

docs/reference/env.md

@@ -173,6 +173,7 @@ slows down processing and may cause CPU spikes due to frequent SSH-connection es
       `https://dstack.example.com/{arch}/{version}/dstack-runner`.
      * `DSTACK_SHIM_DOWNLOAD_URL` – Overrides `dstack-shim` binary download URL. The URL can contain `{version}` and/or `{arch}` placeholders,
       see `DSTACK_RUNNER_DOWNLOAD_URL` for the details.
+     * `DSTACK_GATEWAY_PACKAGE_URL` – Overrides the URL the `dstack` package is installed from on gateway instances (used as `dstack[gateway] @ <URL>`).
      * `DSTACK_DEFAULT_CREDS_DISABLED` – Disables default credentials detection if set. Defaults to `None`.
 
 ## CLI

docs/reference/env/index.html

@@ -5178,6 +5178,7 @@ <h2 id="server">Server<a class="headerlink" href="#server" title="Permanent link
   <code>https://dstack.example.com/{arch}/{version}/dstack-runner</code>.</li>
 <li><code>DSTACK_SHIM_DOWNLOAD_URL</code> – Overrides <code>dstack-shim</code> binary download URL. The URL can contain <code>{version}</code> and/or <code>{arch}</code> placeholders,
   see <code>DSTACK_RUNNER_DOWNLOAD_URL</code> for the details.</li>
+<li><code>DSTACK_GATEWAY_PACKAGE_URL</code> – Overrides the URL the <code>dstack</code> package is installed from on gateway instances (used as <code>dstack[gateway] @ &lt;URL&gt;</code>).</li>
 <li><code>DSTACK_DEFAULT_CREDS_DISABLED</code> – Disables default credentials detection if set. Defaults to <code>None</code>.</li>
 </ul>
 </details>