diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md index 5a5b32fefe..70727d0785 100644 --- a/content/manuals/ai/sandboxes/configuration/environment-files.md +++ b/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. diff --git a/content/manuals/ai/sandboxes/customize/author/capabilities.md b/content/manuals/ai/sandboxes/customize/author/capabilities.md index 1af1e0f20c..50d03ad851 100644 --- a/content/manuals/ai/sandboxes/customize/author/capabilities.md +++ b/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. diff --git a/content/manuals/ai/sandboxes/workflows/development.md b/content/manuals/ai/sandboxes/workflows/development.md index 0dc5bc781b..024cc80d91 100644 --- a/content/manuals/ai/sandboxes/workflows/development.md +++ b/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