guest-agent: document where anonymous scopes are configured

There is no built-in anonymous default, so the sample configs are the only
place a host learns what to open. Fill in `[cvm.guest_agent_api]` in the
shipped `vmm.toml`, in the `dstackup install` renderer, and in the two
dev/test stacks with what an unconfigured 8090 used to serve: the dashboard
plus the identity, version and health it publishes.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Signed-off-by: Kevin Wang <wy721@qq.com>

Author: kvinwang

CHANGELOG.md

@@ -14,7 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - guest: a fresh CVM with a verity volume could take the volume for its data disk and try to LUKS-format it: volumes labelled their data partition `dstack-data`, the data disk's label. `dstack verity` now labels it `dstack-volume-data`, and the guest skips disks that carry a `dstack-volume` partition, so volumes built by older releases are safe too
 
 ### Changed
-- guest-agent: the external listener (port 8090) is no longer anonymous. Every route needs a scope, granted by a signed Ed25519 JWT or by `[cvm.guest_agent_api].anonymous_scopes` in sys-config; the gateway gets its token minted inside the CVM from the app root key. `public_logs` / `public_sysinfo` / `public_tcbinfo` are unchanged and still decide what may leave the TEE. The dashboard is filtered block by block by scope. See `docs/guest-api-auth.md`. An old gateway sees 401s and drops new guests from rotation until it is upgraded
+- guest-agent: the external listener (port 8090) is no longer anonymous. Every route needs a scope, granted by a signed Ed25519 JWT or by `[cvm.guest_agent_api].anonymous_scopes` in sys-config. There is no built-in anonymous default; the sample `vmm.toml` opens `guest:dashboard`, `guest:info`, `guest:version` and `guest:health`, which is what an unconfigured 8090 used to serve, while containers, logs, metrics and app-key attestation stay behind a token. The gateway gets its token minted inside the CVM from the app root key. `public_logs` / `public_sysinfo` / `public_tcbinfo` are unchanged and still decide what may leave the TEE. The dashboard is filtered block by block by scope. See `docs/guest-api-auth.md`. An old gateway sees 401s and drops new guests from rotation until it is upgraded
 - vmm: `qmp_socket` now defaults to `true`. Each CVM's QEMU exposes `qmp.sock` in its work dir, so the host can change disk options or compact a bloated `hda.img` (`blockdev-mirror`) without stopping the CVM. Applies to CVMs started after the change; set `qmp_socket = false` to opt out
 
 ## [0.6.1] - 2026-10-12

docs/guest-api-auth.md

@@ -33,33 +33,53 @@ not passed to the router.
 
 ## Default: nothing anonymous
 
-With no configuration, every scope above requires a token. The gateway still
-works, because it is issued one internally; the dashboard, `/metrics` and the
-log views stop answering to the public.
-
-The app's own SDKs are unaffected: they use the internal Unix socket, which is
+With no `[cvm.guest_agent_api]` block, an anonymous caller is granted nothing:
+the dashboard, its identity block, `/metrics` and the log views all need a
+token. The gateway still works, because it is issued one internally. The app's
+own SDKs are unaffected: they use the internal Unix socket, which is
 unauthenticated and reachable only by the application.
 
+The sample `vmm.toml` ships the block filled in with what an unconfigured 8090
+used to serve, so a host that copies the sample keeps the page it had:
+
+| Scope | Effect |
+|---|---|
+| `guest:version` | `Worker.Version` answers |
+| `guest:health` | `Worker.Health` answers |
+| `guest:info` | the identity block renders |
+| `guest:dashboard` | the page loads at all |
+
+Everything else is about the app's *contents* and stays behind a token even in
+that sample: the container table, `/metrics`, the log views and
+`Worker.GetAttestationForAppKey`.
+
+The dashboard does not fetch `Info` unless a block would show it, so an
+anonymous visitor granted only `guest:dashboard` costs the TEE no attestation.
+
 ## Configuring anonymous access
 
 Anonymous access is a host decision, made in sys-config. The VMM writes it from
 `[cvm.guest_agent_api]`:
 
 ```toml
 [cvm.guest_agent_api]
-anonymous_scopes = ["guest:dashboard", "guest:version", "guest:health"]
+anonymous_scopes = ["guest:dashboard", "guest:version", "guest:health", "guest:info"]
 ```
 
 The same block in the guest's `/dstack/.host-shared/.sys-config.json`:
 
 ```json
 {
   "guest_agent_api": {
-    "anonymous_scopes": ["guest:dashboard", "guest:version", "guest:health"]
+    "anonymous_scopes": ["guest:dashboard", "guest:version", "guest:health", "guest:info"]
   }
 }
 ```
 
+The list is whole, not additive, and there is no built-in default to fall back
+on: omitting `anonymous_scopes`, or leaving the list empty, closes the listener
+to anonymous callers. Removing the block entirely does the same.
+
 Listing `guest:dashboard` without `guest:containers`, `guest:info`, `guest:logs`
 or `guest:metrics` gives an anonymous visitor the page with every block hidden.
 Scopes are independent: each one adds exactly its own block.
@@ -92,6 +112,9 @@ it over on registration, bound to the app id and short-lived:
 
 1. The agent and `dstack-util`, both inside the CVM, derive the same Ed25519
    key: `derive_app_key(app_root_key, "dstack:guest-api:issuer:v1", Ed25519)`.
+   That domain string is final: it is a wire contract between `dstack-util` and
+   the agent, which are upgraded together but may briefly disagree, so it is
+   never versioned again.
 2. `dstack-util` signs a token with `iss = "dstack:guest-api:<app_id>"`,
    `aud = <app_id>`, a 10-minute lifetime, and only the `guest:health` scope.
 3. Registration carries it to the gateway, which presents it on the v1 `Health`
@@ -135,14 +158,21 @@ host cannot alter without changing the app id.
 
 ## Compatibility
 
-A guest with this change answers 401 to an old gateway that presents no token. The
-gateway counts that as unreachable and drops the instance after
+A guest with this change answers 401 to an old gateway that presents no token.
+The gateway counts that as unreachable and drops the instance after
 `failure_threshold` consecutive polls, so a mixed cluster rebalances away from
 new guests until the gateway is upgraded.
 
 During the rollout, either upgrade the gateway first, or leave the host open:
 
 ```toml
 [cvm.guest_agent_api]
-anonymous_scopes = ["guest:version", "guest:health"]
+anonymous_scopes = ["guest:version", "guest:health", "guest:info", "guest:dashboard"]
 ```
+
+The reverse direction is quieter. A new guest registers with an old gateway
+node that does not store `agent_token`; when that record syncs to an upgraded
+node, the missing token means the upgraded node's health probe is refused too.
+The instance drops out of rotation while `order_by_stickiness` keeps routing
+user traffic to it. Upgrade every gateway node in the cluster before rolling
+guests, not just the one the VMM talks to.

dstack/crates/dstack-cli-core/src/config.rs

@@ -348,6 +348,12 @@ qemu_hotplug_off = true
 host_share_mode = "{host_share_mode}"
 qgs_port = 4050
 
+# What an unconfigured 8090 serves: the dashboard, and the identity, version
+# and health it publishes. Containers, logs, metrics and app-key attestation
+# need a token. See docs/guest-api-auth.md.
+[cvm.guest_agent_api]
+anonymous_scopes = ["guest:dashboard", "guest:version", "guest:health", "guest:info"]
+
 [cvm.product]
 sys_vendor = "dstack"
 product_name = "dstack"

dstack/dstack-types/src/lib.rs

@@ -1255,7 +1255,7 @@ pub struct SysConfig {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub mr_config: Option<String>,
     /// Access control for the guest agent's external listener. Absent means
-    /// the code defaults: nothing anonymous, no external issuers.
+    /// nothing anonymous and no external issuers.
     ///
     /// Host-supplied, and deliberately not measured: it decides who may *ask*
     /// the agent, never whether data may leave the TEE. Confidentiality stays
@@ -1273,8 +1273,9 @@ pub struct GuestAgentApiConfig {
     /// Scopes granted to a caller that presents no token.
     ///
     /// Empty by default: an app that wants its dashboard on the internet has
-    /// to say so. This is an exposure choice, not a trust one -- the anonymous
-    /// caller is the same party a public 8090 already served.
+    /// to say so, in `vmm.toml` or in the guest's sys-config. What a host is
+    /// expected to open is spelled out in the sample `vmm.toml` rather than
+    /// here, so the shipped default stays visible where an operator sets it.
     #[serde(default)]
     pub anonymous_scopes: Vec<String>,
     /// Issuers other than the app's own root key.

dstack/vmm/vmm.toml

@@ -109,18 +109,6 @@ tdx_attestation_variant = "auto"
 
 host_share_mode = "9p"
 
-# Access control for the guest agent's external listener (port 8090). Absent
-# means nothing is anonymous: only holders of a token (the gateway, minted
-# inside the CVM) can call it. This is an exposure choice, not a
-# confidentiality one -- what may leave the TEE is still decided by the
-# measured public_logs / public_sysinfo / public_tcbinfo switches in
-# app-compose. See docs/guest-api-auth.md.
-# [cvm.guest_agent_api]
-# anonymous_scopes = ["guest:dashboard", "guest:version", "guest:health"]
-# [[cvm.guest_agent_api.external_issuers]]
-# name = "ops"
-# public_keys = ["<32-byte ed25519 public key, hex>"]
-
 # Default preallocation for a new CVM data disk. This is a host storage
 # policy -- the guest cannot see it and it does not affect measurements -- and
 # a deploy request may pick another mode per VM.
@@ -317,6 +305,23 @@ sanitize_on_attach = false
 # Maximum time for all reset GPUs to become continuously VFIO-ready.
 sbr_timeout_ms = 10000
 
+# Access control for the guest agent's external listener (port 8090). Every
+# route needs a scope, granted by a signed Ed25519 JWT or by the anonymous list
+# below. This is an exposure choice, not a confidentiality one -- what may leave
+# the TEE is still decided by the measured public_logs / public_sysinfo /
+# public_tcbinfo switches in app-compose. See docs/guest-api-auth.md.
+#
+# The list is whole, not additive, and there is no built-in anonymous default:
+# comment the whole block out to refuse anonymous callers entirely. The set
+# below is what an unconfigured 8090 used to serve -- the dashboard, and the
+# identity, version and health it publishes. Containers, logs, metrics and
+# app-key attestation need a token either way.
+[cvm.guest_agent_api]
+anonymous_scopes = ["guest:dashboard", "guest:version", "guest:health", "guest:info"]
+# [[cvm.guest_agent_api.external_issuers]]
+# name = "ops"
+# public_keys = ["<32-byte ed25519 public key, hex>"]
+
 [gateway]
 base_domain = "localhost"
 port = 8082

test-suites/full-stack-compose/scripts/render-config.sh

@@ -216,6 +216,9 @@ exclude = []
 include = []
 allow_attach_all = false
 
+[cvm.guest_agent_api]
+anonymous_scopes = ["guest:dashboard", "guest:version", "guest:health", "guest:info"]
+
 [gateway]
 base_domain = "${BASE_DOMAIN}"
 port = ${GATEWAY1_PROXY_HOST_PORT}

tools/dev-stack.sh

@@ -261,6 +261,10 @@ kms_urls = ["https://$KMS_DOMAIN:$KMS_RPC_LISTEN_PORT"]
 gateway_urls = ["https://$GATEWAY_DOMAIN:$GATEWAY_RPC_LISTEN_PORT"]
 cid_start = $VMM_CID_POOL_START
 cid_pool_size = $VMM_CID_POOL_SIZE
+
+[cvm.guest_agent_api]
+anonymous_scopes = ["guest:dashboard", "guest:version", "guest:health", "guest:info"]
+
 [cvm.port_mapping]
 enabled = $VMM_PORT_MAPPING_ENABLED
 address = "127.0.0.1"