Gregory Anders

This commit **stabilizes** the **container snapshot API** by **removing the experimental gate**, making its functionality generally available. Specifically, it **enables container snapshot and restore operations** within the `workerd/api/container` module by removing the experimental flag checks from both the C++ implementation and header definitions. The change also **integrates the snapshot functionality into the latest API type definitions**, ensuring it is fully exposed for general use. This **feature enablement** allows broader adoption of container snapshotting without requiring experimental flags.

This commit introduces **full container snapshotting** capabilities for **local development environments** within the `workerd` server. It implements new functionality in the **`container-client`** (`src/workerd/server/container-client.c++`) to leverage Docker's `commit` command, creating new images from running containers for easy state restoration. This **new feature** enhances the developer workflow by allowing saving and loading of container states, while explicitly forbidding memory snapshots due to design limitations. The change includes updates to the Cap'n Proto API for Docker interactions and comprehensive test cases (`src/workerd/server/tests/container-client/test.js`) to ensure robustness.

This commit introduces a **new `snapshotContainer` API** to the **Workerd runtime**, enabling the creation of comprehensive "full container" snapshots that capture the entire disk/filesystem and optionally the container's memory state. This **feature addition** provides a powerful mechanism for **container state management**, allowing for the persistence and restoration of a complete container environment, distinct from existing directory-only snapshots. The implementation involves significant changes across the **`Container` API**, **Cap'n Proto schema**, and **server-side logic**, including refactoring the `start` method to support restoring a single container snapshot alongside multiple directory snapshots. This new capability greatly enhances **container lifecycle management** and **state persistence** within the Workerd ecosystem.

This commit **refines the Workerd API type generation** to prevent experimental container-related types from appearing in standard TypeScript definitions. It **hides** `ContainerDirectorySnapshot`, `ContainerSnapshotRestoreParams`, and properties like `hardTimeout` and `snapshots` from `ContainerStartupOptions` in `types/generated-snapshot/latest/index.ts` unless the `WorkerdExperimental` flag is active. This **maintenance** change ensures that users not opting into experimental features will not encounter or depend on unstable container APIs in their type-checked code, improving API stability and clarity.

This commit implements a **new feature** to **clone snapshot volumes** when restoring a snapshot, ensuring that the restored snapshot correctly masks the mount point's current contents and maintains snapshot immutability. This significantly improves the **`workerd` server's snapshot restore mechanism** by aligning its semantics with production behavior and resolving **performance issues** on macOS related to the previous archive API. The core logic in `src/workerd/server/container-client.c++` now integrates volume cloning into container creation and startup flows. This is supported by API changes in `src/workerd/server/container-client.h` and a Docker API schema update in `src/workerd/server/docker-api.capnp` to enable `NoCopy` mounts. New test cases in `src/workerd/server/container-client-test.c++` and `src/workerd/server/tests/container-client/test.js` validate the correct handling of snapshot cloning and restore logic.

This commit **enforces a new constraint** within the **`workerd` container API**, preventing users from restoring directory snapshots directly to the root directory. The `Container::start` method in `src/workerd/api/container.c++` was modified to incorporate this **critical validation rule**, aligning behavior with production requirements and Docker's volume mounting restrictions. This **feature enhancement** introduces a new utility function `parseRestorePath` to facilitate this validation. New test cases in `src/workerd/server/tests/container-client/test.js` confirm that attempts to restore to the root or using relative mount points are correctly rejected, ensuring the robustness of the **snapshot restoration mechanism** and preventing potential issues in container operations.

This commit introduces a **new experimental `snapshotDirectory` API** within the **`container` subsystem**, enabling the **snapshotting and restoration of container directories**. It provides a concrete implementation using **Docker volumes** for local development, integrating snapshot creation and restoration directly into the **`workerd` container lifecycle**. This **feature enhancement** is designed to support tools like **Wrangler** for managing local development state and lays crucial groundwork for future persistent storage capabilities within **Cloudflare Workers**. The changes span **API definitions**, **Cap'n Proto schemas**, **Docker API interactions** in `src/workerd/server/container-client.c++`, and comprehensive **test coverage** for the new functionality.

This commit **reverts** the prior implementation of the **containers snapshot API**, effectively removing all associated code and functionality. It undoes changes across the **`workerd` API**, **server-side container client**, **Cap'n Proto schema definitions**, and **build configurations**. This **maintenance** action removes the experimental snapshot feature, including its C++ implementation, client-side components, and generated TypeScript types, from the project. Consequently, the **containers snapshot API** is no longer present in the codebase, indicating a pause or re-evaluation of this feature's development.

This commit introduces a **new experimental `snapshotDirectory` API** for **containers**, enabling the creation and restoration of directory snapshots. It provides a concrete implementation leveraging **Docker volumes** within the `workerd` server's `container-client`, including logic for volume creation, deletion, and temporary container management, as well as snapshot restoration during container startup. This **new capability** lays the groundwork for future Cloudflare Workers features and is immediately usable by Wrangler for local development, with extensive test coverage added for the new API.

This commit **reimplements the `containers list` command** within **Wrangler** to fetch container application data directly from **Dash API endpoints**, replacing the previous data fetching mechanism. It introduces a new `DashApplication` type and a `listDashApplications` service method in `packages/containers-shared` to support this new API integration. This **feature implementation** significantly refactors the command's logic in `packages/wrangler/src/containers/list.ts`, including new functions for state derivation, pagination, and output rendering. The change also updates related `containers instances` functionality, such as renaming `ContainerState` to `InstanceState` and adding `--per-page` validation, alongside comprehensive new tests for API interaction and output formats.

This commit performs a **refactoring** to enhance the clarity and consistency of **Wrangler CLI** help messages. It specifically removes the superfluous adjective "clean" from the description of the `--json` option across a wide range of commands. This **maintenance** change affects numerous **Wrangler** features, including **AI**, **D1**, **Pages**, **Vectorize**, and **Versions**, by updating their respective command definitions and associated test snapshots. The primary impact is a more concise and accurate user experience when viewing command-line help for these `wrangler` subcommands.

This commit **adds comprehensive documentation** for the new **SSH support in Containers**, enabling users to securely access their running instances. It introduces a new changelog entry and a dedicated documentation page (`ssh.mdx`) detailing how to configure and connect to Container instances via SSH, along with an update to the main Containers index. Furthermore, the **Wrangler configuration** documentation is expanded to include `wrangler_ssh` and `authorized_keys` properties, and the new `wrangler containers ssh` command is thoroughly documented. This **new capability documentation** provides essential guides for developers to leverage SSH with their Container deployments.

This commit **enhances the Wrangler CLI documentation** by adding comprehensive details for the newly introduced `wrangler containers instances` command. It includes a new entry in the **changelog** (`src/content/changelog/containers/2026-03-12-wrangler-containers-instances.mdx`) to record this feature's availability. Furthermore, the **`containers` command documentation** (`src/content/partials/workers/wrangler-commands/containers.mdx`) is updated with usage instructions and a minor typo correction. This **documentation update** ensures users can effectively understand and utilize the `wrangler containers instances` functionality.

This commit **introduces a new `wrangler containers instances` command**, allowing users to list and inspect running instances of their Cloudflare Container applications directly from the CLI. To facilitate this **new capability**, the **`containers-shared` package** was significantly updated to support **paginated API requests** through new types like `PaginatedResult` and `ResultInfo`, and new data models for `DashApplicationInstance` and `DashApplicationDurableObjectInstance`. The command itself provides detailed instance information, supports various output formats (e.g., table, JSON), and includes comprehensive unit tests. Additionally, the `onKeyPress` utility in Wrangler received an `escapeCodeTimeout` option to improve responsiveness for interactive prompts.

This commit **deprecates and hides OpenSSH options** from the `wrangler ssh` command, streamlining its interface and preventing direct passthrough of these flags. It primarily affects the **`wrangler` package's SSH command construction and option parsing** within `packages/wrangler/src/containers/ssh.ts`, specifically modifying `buildSshCommand` and `parseSshOptions`. This is a **feature modification and deprecation** aimed at simplifying the user experience and ensuring `wrangler` manages SSH connections more directly. New tests in `packages/wrangler/src/__tests__/containers/ssh.test.ts` verify this behavior, and a changeset documents the change.

This commit **adds comprehensive documentation** for the `containers_pid_namespace` **compatibility flag** within the `workerd` project. It introduces a new markdown page, `src/content/compatibility-flags/containers-pid-namespace.md`, detailing the flag's behavior concerning **isolated PID namespaces** for containers. This **documentation update** provides crucial information for users, clarifying how this feature impacts container isolation and execution within the `workerd` runtime. The addition improves the overall clarity and usability of the system by ensuring that the functionality of this important flag is well-understood.

This commit **introduces a new compatibility date entry** named `containers_pid_namespace` within the **`workerd/io` subsystem**. This **feature addition** updates the `src/workerd/io/compatibility-date.capnp` schema, allowing `workerd` to manage and enforce behavior changes related to **container PID namespaces**. By adding this entry, the system gains the ability to control the rollout of new features or breaking changes associated with container process isolation based on a specific compatibility date.

This commit **corrects a factual error** within the **Containers changelog documentation**. Specifically, it updates the `2026-02-24-higher-container-resource-limits.mdx` entry to accurately reflect the number of concurrent 'lite' instance types available, changing the figure from 'over 20,000' to '15,000'. This **documentation fix** ensures that users and stakeholders referencing the **Cloudflare Containers** resource limits are provided with precise and up-to-date information.

This change improves the robustness of the `workerd` server's container management by adding retries for container destruction on conflict, preventing failures in cleanup operations.

This is an isolated change to the test suite for the `workerd` server's container client, adding a new test case for the `containers_pid_namespace` compatibility flag. It has no production impact.