Dstack

Quick agent flow (detached runs)

1. Show plan: echo "n" | dstack apply -f <config>
2. If plan is OK and user confirms, apply detached: dstack apply -f <config> -y -d
3. Check status once: dstack ps -v
4. If dev-environment or task with ports and running: attach to surface IDE link/ports/SSH alias (agent runs attach in background); ask to open link
5. If attach fails in sandbox: request escalation; if not approved, ask the user to run dstack attach locally and share the output

CRITICAL: Never propose dstack CLI commands or YAML syntaxes that don't exist.

• Only use CLI commands and YAML syntax documented here or verified via --help
• If uncertain about a command or its syntax, check the links or use --help

NEVER do the following:

• Invent CLI flags not documented here or shown in --help
• Guess YAML property names - verify in configuration reference links
• Run dstack apply for runs without -d in automated contexts (blocks indefinitely)
• Retry failed commands without addressing the underlying error
• Summarize or reformat tabular CLI output - show it as-is
• Use echo "y" | when -y flag is available
• Assume a command succeeded without checking output for errors

Agent execution guidelines

Output accuracy

• NEVER reformat, summarize, or paraphrase CLI output. Display tables, status output, and error messages exactly as returned.
• When showing command results, use code blocks to preserve formatting.
• If output is truncated due to length, indicate this clearly (e.g., "Output truncated. Full output shows X entries.").

Verification before execution

• When uncertain about any CLI flag or YAML property, run dstack <command> --help first.
• Never guess or invent flags. Example verification commands:

  dstack --help                               # List all commands
  dstack apply --help <configuration type>    # Flags for apply per configuration type (dev-environment, task, service, fleet, etc)
  dstack fleet --help                         # Fleet subcommands
  dstack ps --help                            # Flags for ps
  

• If a command or flag isn't documented, it doesn't exist.

Command timing and confirmation handling

Commands that stream indefinitely in the foreground:

• dstack attach
• dstack apply without -d for runs
• dstack ps -w

Agents should avoid blocking: use -d, timeouts, or background attach. When attach is needed, run it in the background by default (nohup ...), but describe it to the user simply as "attach" unless they ask for a live foreground session. Prefer dstack ps -v and poll in a loop if the user wants to watch status.

All other commands: Use 10-60s timeout. Most complete within this range. While waiting, monitor the output - it may contain errors, warnings, or prompts requiring attention.

Confirmation handling:

• dstack apply, dstack stop, dstack fleet delete require confirmation
• Use -y flag to auto-confirm when user has already approved
• For dstack stop, always use -y after the user confirms to avoid interactive prompts
• Use echo "n" | to preview dstack apply plan without executing (avoid echo "y" |, prefer -y)

Best practices:

• Prefer modifying configuration files over passing parameters to dstack apply (unless it's an exception)
• When user confirms deletion/stop operations, use -y flag to skip confirmation prompts

Detached run follow-up (after -d)

After submitting a run with -d (dev-environment, task, service), first determine whether submission failed. If the apply output shows errors (validation, no offers, etc.), stop and surface the error.

If the run was submitted, do a quick status check with dstack ps -v, then guide the user through relevant next steps: If you need to prompt for next actions, be explicit about the dstack step and command (avoid vague questions). When speaking to the user, refer to the action as "attach" (not "background attach").

• Monitor status: Report the current status (provisioning/pulling/running/finished) and offer to keep watching. Poll dstack ps -v every 10-20s if the user wants updates.
• Attach when running: For agents, run attach in the background by default so the session does not block. Use it to capture IDE links/SSH alias or enable port forwarding; when describing the action to the user, just say "attach".
• Dev environments or tasks with ports: Once running, attach to surface the IDE link/port forwarding/SSH alias, then ask whether to open the IDE link. Never open links without explicit approval.
• Services: Prefer using service endpoints. Attach only if the user explicitly needs port forwarding or full log replay.
• Tasks without ports: Default to dstack logs for progress; attach only if full log replay is required.

Attaching behavior (blocking vs non-blocking)

dstack attach runs until interrupted and blocks the terminal. Agents must avoid indefinite blocking. If a brief attach is needed, use a timeout to capture initial output (IDE link, SSH alias) and then detach.

Note: dstack attach writes SSH alias info under ~/.dstack/ssh/config (and may update ~/.ssh/config) to enable ssh <run name>, IDE connections, port forwarding, and real-time logs (dstack attach --logs). If the sandbox cannot write there, the alias will not be created.

Permissions guardrail: If dstack attach fails due to sandbox permissions, request permission escalation to run it outside the sandbox. If escalation isn’t approved or attach still fails, ask the user to run dstack attach locally and share the IDE link/SSH alias output.

Background attach (non-blocking default for agents):

nohup dstack attach <run name> --logs > /tmp/<run name>.attach.log 2>&1 & echo $! > /tmp/<run name>.attach.pid

Then read the output:

tail -n 50 /tmp/<run name>.attach.log

Offer live follow only if asked:

tail -f /tmp/<run name>.attach.log

Stop the background attach (preferred):

kill "$(cat /tmp/<run name>.attach.pid)"

If the PID file is missing, fall back to a specific match (avoid killing all attaches):

pkill -f "dstack attach <run name>"

Why this helps: it keeps the attach session alive (including port forwarding) while the agent remains usable. IDE links and SSH instructions appear in the log file -- surface them and ask whether to open the link (open "<link>" on macOS, xdg-open "<link>" on Linux) only after explicit approval.

If background attach fails in the sandbox (permissions writing ~/.dstack or ~/.ssh, timeouts), request escalation to run attach outside the sandbox. If not approved, ask the user to run attach locally and share the IDE link/SSH alias.

Interpreting user requests

"Run something": When the user asks to run a workload (dev environment, task, service), use dstack apply with the appropriate configuration. Note: dstack run only supports dstack run get --json for retrieving run details -- it cannot start workloads.

"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.

Configuration types

dstack supports five main configuration types. Configuration files can be named <name>.dstack.yml or simply .dstack.yml.

Common parameters: All run configurations (dev environments, tasks, services) support many parameters including:

• Git integration: Clone repos automatically (repo), mount existing repos (repos)
• File upload: files (see concept docs for examples)
• Docker support: Use custom Docker images (image); use docker: true if you want to use Docker from inside the container (VM-based backends only)
• Environment: Set environment variables (env), often via .envrc. Secrets are supported but less common.
• Storage: Persistent network volumes (volumes), specify disk size
• Resources: Define GPU, CPU, memory, and disk requirements

Best practices:

• Prefer giving configurations a name property for easier management
• When configurations need credentials (API keys, tokens), list only env var names in the env section (e.g., - HF_TOKEN), not values. Recommend storing actual values in a .envrc file alongside the configuration, applied via source .envrc && dstack apply.
• python and image are mutually exclusive in run configurations. If image is set, do not set python.

files and repos intent policy

Use files and repos only when the user intends to use local/repo files inside the run.

• If user asks to use project code/data/config in the run, then add files or repos as appropriate.
• If it is totally unclear whether files ore repos must be mounted, ask one explicit clarification question or default to not mounting.

files guidance:

• Relative paths are valid and preferred for local project files.
• A relative files path is placed under the run's working_dir (default or set by user).

repos + image/working directory guidance:

• With non-default Docker images, prefer explicit absolute mount targets for repos (e.g., .:/dstack/run).
• When setting an explicit repo mount path, also set working_dir to the same path.
• Reason: custom images may have a different/non-empty default working directory, and mounting a repo into a non-empty path can fail.
• With dstack default images, the default working_dir is already /dstack/run.

AMD image selection policy

When resources.gpu targets AMD (e.g., MI300X), you have to set image.

Use the official ROCm Docker image namespace as the default source: https://hub.docker.com/u/rocm

1. If the user provides an image, use it as-is. Do not override user intent.
2. If the user asks for a specific framework/runtime, prefer official rocm/* framework images and select tags with the latest available ROCm version by default. Pick the most recent ROCm-compatible tag appropriate for the requested AMD GPU family.
   • SGLang: rocm/sgl-dev
   • vLLM: rocm/vllm
   • PyTorch-only: rocm/pytorch
3. If no framework is specified (generic AMD dev/task use case), default to rocm/dev-ubuntu-24.04.

Additional guidance:

• Prefer :latest where applicable for generic/default recommendations, unless the user asks for pinning or reproducibility.
• Ensure AMD-compatible images include ROCm userspace/tooling; avoid non-ROCm images for AMD GPU runs.

1. Dev environments

Use for: Interactive development with IDE integration (VS Code, Cursor, etc.).