docs: clarify sandbox port address families

Kit port guidance omitted the IPv4 default and backend address-family restrictions. Explain v3 family selection and composition, and qualify environment-file and CLI publication guidance for the experimental Runtime backend.

content/manuals/ai/sandboxes/configuration/environment-files.md

@@ -907,5 +907,10 @@ by a kit but omitted from this list receive an ephemeral host port.
 Set `protocol: tcp` to bind both IPv4 and IPv6. Leave `hostIP` unset for a
 dual-stack binding because an explicit address binds only its own IP family.
 
+The experimental Runtime backend publishes ports on IPv4 loopback only.
+Use `protocol: tcp4` or `protocol: udp4` and omit `host` to let it assign a
+host port. It rejects `tcp6` and `udp6`. Bare `tcp` and `udp` require
+`hostIP: 127.0.0.1`.
+
 If a port can't be published, sandbox creation fails and removes the new
 sandbox.

content/manuals/ai/sandboxes/customize/author/capabilities.md

@@ -36,7 +36,7 @@ All capability names in the table have the `com.docker.sandbox/` prefix.
 | [`long-running@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/long-running@1.md) | v0.47.0 | Unsupported | Keeps a local sandbox running after its last session disconnects. |
 | [`network-policy@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@1.md) | v0.45.0 | Limited: v0.45.0 | Cloud sandboxes keep installation-phase network access after setup. |
 | [`network-policy@2`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@2.md) | v0.45.0 | Limited: v0.45.0 | Cloud sandboxes enforce host rules, but not HTTP method or path restrictions. Installation-phase access remains after setup. |
-| [`port@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/port@1.md) | v0.45.0 | Limited: v0.45.0 | Cloud sandboxes expose TCP ports only. |
+| [`port@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/port@1.md) | v0.45.0 | Limited: v0.45.0 | Cloud sandboxes expose IPv4 TCP ports only. The experimental Runtime backend supports IPv4 only. See [Port address families](#port-address-families). |
 | [`privileged@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/privileged@1.md) | v0.48.0 | Unsupported | Accepted by the local runtime, which runs Docker-in-Docker containers in privileged mode inside the sandbox VM. |
 | [`resources@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/resources@1.md) | Limited: v0.45.0 | Limited: v0.45.0 | Workload CPU and memory defaults are applied. The `gpu` field does not select GPUs; cloud creation rejects a required GPU request. |
 | [`sbx@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/sbx@1.md) | v0.45.0 | v0.45.0 | Docker Sandboxes launches the agent using the workload command. |
@@ -44,6 +44,22 @@ All capability names in the table have the `com.docker.sandbox/` prefix.
 | [`usb-device@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/usb-device@1.md) | Unsupported | Unsupported | Kit requests for USB device access are not supported. |
 | [`volume@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/volume@1.md) | v0.45.0 | Limited: v0.45.0 | Local sandboxes provide block storage or tmpfs and [retain block volumes across removal and recreation](../use-kits.md#keep-kit-data-when-recreating-a-sandbox). Cloud sandboxes use ordinary sandbox disk at the declared paths, including for tmpfs requests. |
 
+## Port address families
+
+For v3 `port@1` entries, `family` selects the address families used to publish
+the port: `ipv4`, `ipv6`, or `dual` for both. If no kit specifies a family,
+the port defaults to IPv4, even with an explicit `transport: tcp`. Use
+`family: dual` when the service needs both IPv4 and IPv6 clients.
+
+When kits declare the same port and transport, an entry without `family`
+uses the family specified by another kit in the set. Kits that specify
+conflicting families for that port cannot be used together.
+
+Cloud sandboxes support IPv4 TCP ports only. The experimental Runtime backend
+supports IPv4 TCP and UDP ports on host loopback only. Both reject required
+`ipv6` and `dual` entries and skip optional ones. For capability syntax and
+examples, follow the `port@1` specification link in the table.
+
 ## Capability groups
 
 Docker Sandboxes supports capability groups in `sbx` v0.48.0 and later.

content/manuals/ai/sandboxes/workflows/development.md

@@ -97,6 +97,10 @@ those require the sandboxed service to listen on IPv6 as well — bind it to
 `[::]` — or a client arriving over `::1` has its connection accepted and then
 reset.
 
+The experimental Runtime backend publishes ports on IPv4 loopback only.
+Use a sandbox port without a host port, such as `--publish 3000` for TCP or
+`--publish 3000/udp4` for UDP. It rejects dual-stack and IPv6 publication.
+
 Published ports survive restarts: `sbx` re-publishes them when the sandbox or
 the daemon restarts. Explicit host ports are reused, while a port published with
 an OS-assigned host port, such as `--publish 3000`, gets a different host port