Skip to content

Commit cfea44e

Browse files
Update SKILL.md to standardize run name formatting and add permissions guardrail for dstack attach (#3555)
1 parent 8ff914b commit cfea44e

File tree

1 file changed

+12
-10
lines changed

1 file changed

+12
-10
lines changed

skills/dstack/SKILL.md

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -101,27 +101,29 @@ If you need to prompt for next actions, be explicit about the dstack step and co
101101

102102
`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.
103103

104-
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.
104+
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.
105+
106+
**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.
105107

106108
**Background attach (non-blocking default for agents):**
107109
```bash
108-
nohup dstack attach <run-name> --logs > /tmp/<run-name>.attach.log 2>&1 & echo $! > /tmp/<run-name>.attach.pid
110+
nohup dstack attach <run name> --logs > /tmp/<run name>.attach.log 2>&1 & echo $! > /tmp/<run name>.attach.pid
109111
```
110112
Then read the output:
111113
```bash
112-
tail -n 50 /tmp/<run-name>.attach.log
114+
tail -n 50 /tmp/<run name>.attach.log
113115
```
114116
Offer live follow only if asked:
115117
```bash
116-
tail -f /tmp/<run-name>.attach.log
118+
tail -f /tmp/<run name>.attach.log
117119
```
118120
Stop the background attach (preferred):
119121
```bash
120-
kill "$(cat /tmp/<run-name>.attach.pid)"
122+
kill "$(cat /tmp/<run name>.attach.pid)"
121123
```
122124
If the PID file is missing, fall back to a specific match (avoid killing all attaches):
123125
```bash
124-
pkill -f "dstack attach <run-name>"
126+
pkill -f "dstack attach <run name>"
125127
```
126128
**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.
127129

@@ -131,7 +133,7 @@ If background attach fails in the sandbox (permissions writing `~/.dstack` or `~
131133

132134
**"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.
133135

134-
**"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.
136+
**"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.
135137

136138
## Configuration types
137139

@@ -187,7 +189,7 @@ resources:
187189
gpu: A100:40GB:2
188190
```
189191
190-
**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.
192+
**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.
191193

192194
**Distributed training:** Multi-node tasks are supported (e.g., via `nodes`) and require fleets that support inter-node communication (see `placement: cluster` in fleets).
193195

@@ -217,10 +219,10 @@ resources:
217219
```
218220

219221
**Service endpoints:**
220-
- Without gateway: `<dstack server URL>/proxy/services/<project name>/<run name>/`
222+
- Without gateway: `<dstack server URL>/proxy/services/f/<run name>/`
221223
- With gateway: `https://<run name>.<gateway domain>/`
222224
- Authentication: Unless `auth` is `false`, include `Authorization: Bearer <DSTACK_TOKEN>` on all service requests.
223-
- OpenAI-compatible models: Use `service.url` from `dstack run get <run-name> --json` and append `/v1` as the base URL; do **not** use deprecated `service.model.base_url` for requests.
225+
- OpenAI-compatible models: Use `service.url` from `dstack run get <run name> --json` and append `/v1` as the base URL; do **not** use deprecated `service.model.base_url` for requests.
224226
- Example (with gateway):
225227
```bash
226228
curl -sS -X POST "https://<run name>.<gateway domain>/v1/chat/completions" \

0 commit comments

Comments
 (0)