feat(compose): add persistent Docker Compose support

[RobertDeRose]

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update

Motivation and Context

Inspired by the k8s' plugin implementation and container machines, this feels like the correct way to finally support docker-compose.yml workflows in an efficient way that doesn't require a full compose-to-container translation layer.

This adds container compose support backed by a persistent Linux container machine
running Docker Engine and the real Docker Compose CLI.

This provides a Docker-compatible Compose workflow without Docker Desktop while
keeping Compose state isolated inside a managed compose machine.

What Changed

• Added the container compose plugin.
• Automatically builds and provisions the bundled Compose machine image.
• Persists the compose machine and its Docker data across invocations.
• Forwards Compose arguments unchanged to /usr/bin/docker compose.
• Added container machine start for generic stopped-machine recovery.
• Added optional Docker socket access through --socket-path.
• Added machine DNS aliases and published-port diagnostics.
• Added configurable CPU, memory, and idle-shutdown settings.
• Added ownership tokens and safe orphan/cancellation handling.
• Added daemon-root-aware configuration loading.
• Documented lifecycle, filesystem, networking, socket, and configuration behavior.

Important Behavior

• container compose down removes Compose resources but does not delete or stop the machine.
• All Compose projects share the persistent compose machine.
• Bind mounts must be below the mounted macOS home directory.
• Published ports are reachable through the Compose machine address, not automatically through macOS loopback.
• --socket-path reports the endpoint only; it never starts the machine.
• Configuration changes require restarting the container service.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

Validation completed:

• 814 unit tests across 91 suites passed.
• Machine lifecycle integration tests passed, including first boot and starting a stopped machine.
• Warnings-as-errors build passed.
• git diff --check passed.

Related Issues and Discussions

• compose support? #55 — “compose support?” — closed request for Docker Compose file support.
• [Request]: Support Docker Compose Files #235 — “Support Docker Compose Files” — closed duplicate/related request.
• Discussion Creating Docker Compose for Container #320 — discusses implementing Compose as a plugin.
• Discussion Expanding Support for Plugins #1410 — ongoing plugin/API compatibility discussion.
• PR Add Compose #239 and PR Compose functionality using familiar docker-compose syntax for container #398 — prior Compose-related implementations.

[stephenlclarke]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

[RobertDeRose]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

Updated based on your comment.

[jglogan]

Hi Robert, thank you for your contribution, but embedding docker/compose is not within the scope of this project. It requires far more effort to maintain than the k8s capability.

We've answered it in many prior issues, PRs, and discussion topics, but the TL;DR is that we'd prefer Compose to be an external plugin (see the work of @stephenlclarke, @Mcrich23, and others).

[RobertDeRose]

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update

Motivation and Context

Inspired by the k8s' plugin implementation and container machines, this feels like the correct way to finally support docker-compose.yml workflows in an efficient way that doesn't require a full compose-to-container translation layer.

This adds container compose support backed by a persistent Linux container machine
running Docker Engine and the real Docker Compose CLI.

This provides a Docker-compatible Compose workflow without Docker Desktop while
keeping Compose state isolated inside a managed compose machine.

What Changed

• Added the container compose plugin.
• Automatically builds and provisions the bundled Compose machine image.
• Persists the compose machine and its Docker data across invocations.
• Forwards Compose arguments unchanged to /usr/bin/docker compose.
• Added container machine start for generic stopped-machine recovery.
• Added optional Docker socket access through --socket-path.
• Added machine DNS aliases and published-port diagnostics.
• Added configurable CPU, memory, and idle-shutdown settings.
• Added ownership tokens and safe orphan/cancellation handling.
• Added daemon-root-aware configuration loading.
• Documented lifecycle, filesystem, networking, socket, and configuration behavior.

Important Behavior

• container compose down removes Compose resources but does not delete or stop the machine.
• All Compose projects share the persistent compose machine.
• Bind mounts must be below the mounted macOS home directory.
• Published ports are reachable through the Compose machine address, not automatically through macOS loopback.
• --socket-path reports the endpoint only; it never starts the machine.
• Configuration changes require restarting the container service.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

Validation completed:

• 814 unit tests across 91 suites passed.
• Machine lifecycle integration tests passed, including first boot and starting a stopped machine.
• Warnings-as-errors build passed.
• git diff --check passed.

Related Issues and Discussions

• compose support? #55 — “compose support?” — closed request for Docker Compose file support.
• [Request]: Support Docker Compose Files #235 — “Support Docker Compose Files” — closed duplicate/related request.
• Discussion Creating Docker Compose for Container #320 — discusses implementing Compose as a plugin.
• Discussion Expanding Support for Plugins #1410 — ongoing plugin/API compatibility discussion.
• PR Add Compose #239 and PR Compose functionality using familiar docker-compose syntax for container #398 — prior Compose-related implementations.

[stephenlclarke]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

[RobertDeRose]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

Updated based on your comment.

[jglogan]

Hi Robert, thank you for your contribution, but embedding docker/compose is not within the scope of this project. It requires far more effort to maintain than the k8s capability.

We've answered it in many prior issues, PRs, and discussion topics, but the TL;DR is that we'd prefer Compose to be an external plugin (see the work of @stephenlclarke, @Mcrich23, and others).

[RobertDeRose]

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update

Motivation and Context

Inspired by the k8s' plugin implementation and container machines, this feels like the correct way to finally support docker-compose.yml workflows in an efficient way that doesn't require a full compose-to-container translation layer.

This adds container compose support backed by a persistent Linux container machine
running Docker Engine and the real Docker Compose CLI.

This provides a Docker-compatible Compose workflow without Docker Desktop while
keeping Compose state isolated inside a managed compose machine.

What Changed

• Added the container compose plugin.
• Automatically builds and provisions the bundled Compose machine image.
• Persists the compose machine and its Docker data across invocations.
• Forwards Compose arguments unchanged to /usr/bin/docker compose.
• Added container machine start for generic stopped-machine recovery.
• Added optional Docker socket access through --socket-path.
• Added machine DNS aliases and published-port diagnostics.
• Added configurable CPU, memory, and idle-shutdown settings.
• Added ownership tokens and safe orphan/cancellation handling.
• Added daemon-root-aware configuration loading.
• Documented lifecycle, filesystem, networking, socket, and configuration behavior.

Important Behavior

• container compose down removes Compose resources but does not delete or stop the machine.
• All Compose projects share the persistent compose machine.
• Bind mounts must be below the mounted macOS home directory.
• Published ports are reachable through the Compose machine address, not automatically through macOS loopback.
• --socket-path reports the endpoint only; it never starts the machine.
• Configuration changes require restarting the container service.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

Validation completed:

• 814 unit tests across 91 suites passed.
• Machine lifecycle integration tests passed, including first boot and starting a stopped machine.
• Warnings-as-errors build passed.
• git diff --check passed.

Related Issues and Discussions

• compose support? #55 — “compose support?” — closed request for Docker Compose file support.
• [Request]: Support Docker Compose Files #235 — “Support Docker Compose Files” — closed duplicate/related request.
• Discussion Creating Docker Compose for Container #320 — discusses implementing Compose as a plugin.
• Discussion Expanding Support for Plugins #1410 — ongoing plugin/API compatibility discussion.
• PR Add Compose #239 and PR Compose functionality using familiar docker-compose syntax for container #398 — prior Compose-related implementations.

[stephenlclarke]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

[RobertDeRose]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

Updated based on your comment.

[jglogan]

Hi Robert, thank you for your contribution, but embedding docker/compose is not within the scope of this project. It requires far more effort to maintain than the k8s capability.

We've answered it in many prior issues, PRs, and discussion topics, but the TL;DR is that we'd prefer Compose to be an external plugin (see the work of @stephenlclarke, @Mcrich23, and others).

[RobertDeRose]

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update

Motivation and Context

Inspired by the k8s' plugin implementation and container machines, this feels like the correct way to finally support docker-compose.yml workflows in an efficient way that doesn't require a full compose-to-container translation layer.

This adds container compose support backed by a persistent Linux container machine
running Docker Engine and the real Docker Compose CLI.

This provides a Docker-compatible Compose workflow without Docker Desktop while
keeping Compose state isolated inside a managed compose machine.

What Changed

• Added the container compose plugin.
• Automatically builds and provisions the bundled Compose machine image.
• Persists the compose machine and its Docker data across invocations.
• Forwards Compose arguments unchanged to /usr/bin/docker compose.
• Added container machine start for generic stopped-machine recovery.
• Added optional Docker socket access through --socket-path.
• Added machine DNS aliases and published-port diagnostics.
• Added configurable CPU, memory, and idle-shutdown settings.
• Added ownership tokens and safe orphan/cancellation handling.
• Added daemon-root-aware configuration loading.
• Documented lifecycle, filesystem, networking, socket, and configuration behavior.

Important Behavior

• container compose down removes Compose resources but does not delete or stop the machine.
• All Compose projects share the persistent compose machine.
• Bind mounts must be below the mounted macOS home directory.
• Published ports are reachable through the Compose machine address, not automatically through macOS loopback.
• --socket-path reports the endpoint only; it never starts the machine.
• Configuration changes require restarting the container service.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

Validation completed:

• 814 unit tests across 91 suites passed.
• Machine lifecycle integration tests passed, including first boot and starting a stopped machine.
• Warnings-as-errors build passed.
• git diff --check passed.

Related Issues and Discussions

• compose support? #55 — “compose support?” — closed request for Docker Compose file support.
• [Request]: Support Docker Compose Files #235 — “Support Docker Compose Files” — closed duplicate/related request.
• Discussion Creating Docker Compose for Container #320 — discusses implementing Compose as a plugin.
• Discussion Expanding Support for Plugins #1410 — ongoing plugin/API compatibility discussion.
• PR Add Compose #239 and PR Compose functionality using familiar docker-compose syntax for container #398 — prior Compose-related implementations.

[stephenlclarke]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

[RobertDeRose]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

Updated based on your comment.

[jglogan]

Hi Robert, thank you for your contribution, but embedding docker/compose is not within the scope of this project. It requires far more effort to maintain than the k8s capability.

We've answered it in many prior issues, PRs, and discussion topics, but the TL;DR is that we'd prefer Compose to be an external plugin (see the work of @stephenlclarke, @Mcrich23, and others).

[RobertDeRose]

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update

Motivation and Context

Inspired by the k8s' plugin implementation and container machines, this feels like the correct way to finally support docker-compose.yml workflows in an efficient way that doesn't require a full compose-to-container translation layer.

This adds container compose support backed by a persistent Linux container machine
running Docker Engine and the real Docker Compose CLI.

This provides a Docker-compatible Compose workflow without Docker Desktop while
keeping Compose state isolated inside a managed compose machine.

What Changed

• Added the container compose plugin.
• Automatically builds and provisions the bundled Compose machine image.
• Persists the compose machine and its Docker data across invocations.
• Forwards Compose arguments unchanged to /usr/bin/docker compose.
• Added container machine start for generic stopped-machine recovery.
• Added optional Docker socket access through --socket-path.
• Added machine DNS aliases and published-port diagnostics.
• Added configurable CPU, memory, and idle-shutdown settings.
• Added ownership tokens and safe orphan/cancellation handling.
• Added daemon-root-aware configuration loading.
• Documented lifecycle, filesystem, networking, socket, and configuration behavior.

Important Behavior

• container compose down removes Compose resources but does not delete or stop the machine.
• All Compose projects share the persistent compose machine.
• Bind mounts must be below the mounted macOS home directory.
• Published ports are reachable through the Compose machine address, not automatically through macOS loopback.
• --socket-path reports the endpoint only; it never starts the machine.
• Configuration changes require restarting the container service.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

Validation completed:

• 814 unit tests across 91 suites passed.
• Machine lifecycle integration tests passed, including first boot and starting a stopped machine.
• Warnings-as-errors build passed.
• git diff --check passed.

Related Issues and Discussions

• compose support? #55 — “compose support?” — closed request for Docker Compose file support.
• [Request]: Support Docker Compose Files #235 — “Support Docker Compose Files” — closed duplicate/related request.
• Discussion Creating Docker Compose for Container #320 — discusses implementing Compose as a plugin.
• Discussion Expanding Support for Plugins #1410 — ongoing plugin/API compatibility discussion.
• PR Add Compose #239 and PR Compose functionality using familiar docker-compose syntax for container #398 — prior Compose-related implementations.

[stephenlclarke]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

[RobertDeRose]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

Updated based on your comment.

[jglogan]

Hi Robert, thank you for your contribution, but embedding docker/compose is not within the scope of this project. It requires far more effort to maintain than the k8s capability.

We've answered it in many prior issues, PRs, and discussion topics, but the TL;DR is that we'd prefer Compose to be an external plugin (see the work of @stephenlclarke, @Mcrich23, and others).

[RobertDeRose]

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update

Motivation and Context

Inspired by the k8s' plugin implementation and container machines, this feels like the correct way to finally support docker-compose.yml workflows in an efficient way that doesn't require a full compose-to-container translation layer.

This adds container compose support backed by a persistent Linux container machine
running Docker Engine and the real Docker Compose CLI.

This provides a Docker-compatible Compose workflow without Docker Desktop while
keeping Compose state isolated inside a managed compose machine.

What Changed

• Added the container compose plugin.
• Automatically builds and provisions the bundled Compose machine image.
• Persists the compose machine and its Docker data across invocations.
• Forwards Compose arguments unchanged to /usr/bin/docker compose.
• Added container machine start for generic stopped-machine recovery.
• Added optional Docker socket access through --socket-path.
• Added machine DNS aliases and published-port diagnostics.
• Added configurable CPU, memory, and idle-shutdown settings.
• Added ownership tokens and safe orphan/cancellation handling.
• Added daemon-root-aware configuration loading.
• Documented lifecycle, filesystem, networking, socket, and configuration behavior.

Important Behavior

• container compose down removes Compose resources but does not delete or stop the machine.
• All Compose projects share the persistent compose machine.
• Bind mounts must be below the mounted macOS home directory.
• Published ports are reachable through the Compose machine address, not automatically through macOS loopback.
• --socket-path reports the endpoint only; it never starts the machine.
• Configuration changes require restarting the container service.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

Validation completed:

• 814 unit tests across 91 suites passed.
• Machine lifecycle integration tests passed, including first boot and starting a stopped machine.
• Warnings-as-errors build passed.
• git diff --check passed.

Related Issues and Discussions

• compose support? #55 — “compose support?” — closed request for Docker Compose file support.
• [Request]: Support Docker Compose Files #235 — “Support Docker Compose Files” — closed duplicate/related request.
• Discussion Creating Docker Compose for Container #320 — discusses implementing Compose as a plugin.
• Discussion Expanding Support for Plugins #1410 — ongoing plugin/API compatibility discussion.
• PR Add Compose #239 and PR Compose functionality using familiar docker-compose syntax for container #398 — prior Compose-related implementations.

[stephenlclarke]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

[RobertDeRose]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

Updated based on your comment.

[jglogan]

Hi Robert, thank you for your contribution, but embedding docker/compose is not within the scope of this project. It requires far more effort to maintain than the k8s capability.

We've answered it in many prior issues, PRs, and discussion topics, but the TL;DR is that we'd prefer Compose to be an external plugin (see the work of @stephenlclarke, @Mcrich23, and others).

[RobertDeRose]

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update

Motivation and Context

Inspired by the k8s' plugin implementation and container machines, this feels like the correct way to finally support docker-compose.yml workflows in an efficient way that doesn't require a full compose-to-container translation layer.

This adds container compose support backed by a persistent Linux container machine
running Docker Engine and the real Docker Compose CLI.

This provides a Docker-compatible Compose workflow without Docker Desktop while
keeping Compose state isolated inside a managed compose machine.

What Changed

• Added the container compose plugin.
• Automatically builds and provisions the bundled Compose machine image.
• Persists the compose machine and its Docker data across invocations.
• Forwards Compose arguments unchanged to /usr/bin/docker compose.
• Added container machine start for generic stopped-machine recovery.
• Added optional Docker socket access through --socket-path.
• Added machine DNS aliases and published-port diagnostics.
• Added configurable CPU, memory, and idle-shutdown settings.
• Added ownership tokens and safe orphan/cancellation handling.
• Added daemon-root-aware configuration loading.
• Documented lifecycle, filesystem, networking, socket, and configuration behavior.

Important Behavior

• container compose down removes Compose resources but does not delete or stop the machine.
• All Compose projects share the persistent compose machine.
• Bind mounts must be below the mounted macOS home directory.
• Published ports are reachable through the Compose machine address, not automatically through macOS loopback.
• --socket-path reports the endpoint only; it never starts the machine.
• Configuration changes require restarting the container service.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

Validation completed:

• 814 unit tests across 91 suites passed.
• Machine lifecycle integration tests passed, including first boot and starting a stopped machine.
• Warnings-as-errors build passed.
• git diff --check passed.

Related Issues and Discussions

• compose support? #55 — “compose support?” — closed request for Docker Compose file support.
• [Request]: Support Docker Compose Files #235 — “Support Docker Compose Files” — closed duplicate/related request.
• Discussion Creating Docker Compose for Container #320 — discusses implementing Compose as a plugin.
• Discussion Expanding Support for Plugins #1410 — ongoing plugin/API compatibility discussion.
• PR Add Compose #239 and PR Compose functionality using familiar docker-compose syntax for container #398 — prior Compose-related implementations.

[stephenlclarke]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

[RobertDeRose]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

Updated based on your comment.

[jglogan]

Hi Robert, thank you for your contribution, but embedding docker/compose is not within the scope of this project. It requires far more effort to maintain than the k8s capability.

We've answered it in many prior issues, PRs, and discussion topics, but the TL;DR is that we'd prefer Compose to be an external plugin (see the work of @stephenlclarke, @Mcrich23, and others).

[RobertDeRose]

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update

Motivation and Context

Inspired by the k8s' plugin implementation and container machines, this feels like the correct way to finally support docker-compose.yml workflows in an efficient way that doesn't require a full compose-to-container translation layer.

This adds container compose support backed by a persistent Linux container machine
running Docker Engine and the real Docker Compose CLI.

This provides a Docker-compatible Compose workflow without Docker Desktop while
keeping Compose state isolated inside a managed compose machine.

What Changed

• Added the container compose plugin.
• Automatically builds and provisions the bundled Compose machine image.
• Persists the compose machine and its Docker data across invocations.
• Forwards Compose arguments unchanged to /usr/bin/docker compose.
• Added container machine start for generic stopped-machine recovery.
• Added optional Docker socket access through --socket-path.
• Added machine DNS aliases and published-port diagnostics.
• Added configurable CPU, memory, and idle-shutdown settings.
• Added ownership tokens and safe orphan/cancellation handling.
• Added daemon-root-aware configuration loading.
• Documented lifecycle, filesystem, networking, socket, and configuration behavior.

Important Behavior

• container compose down removes Compose resources but does not delete or stop the machine.
• All Compose projects share the persistent compose machine.
• Bind mounts must be below the mounted macOS home directory.
• Published ports are reachable through the Compose machine address, not automatically through macOS loopback.
• --socket-path reports the endpoint only; it never starts the machine.
• Configuration changes require restarting the container service.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

Validation completed:

• 814 unit tests across 91 suites passed.
• Machine lifecycle integration tests passed, including first boot and starting a stopped machine.
• Warnings-as-errors build passed.
• git diff --check passed.

Related Issues and Discussions

• compose support? #55 — “compose support?” — closed request for Docker Compose file support.
• [Request]: Support Docker Compose Files #235 — “Support Docker Compose Files” — closed duplicate/related request.
• Discussion Creating Docker Compose for Container #320 — discusses implementing Compose as a plugin.
• Discussion Expanding Support for Plugins #1410 — ongoing plugin/API compatibility discussion.
• PR Add Compose #239 and PR Compose functionality using familiar docker-compose syntax for container #398 — prior Compose-related implementations.

[stephenlclarke]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

[RobertDeRose]

Nice approach. Could the top-level docs make the dependency boundary explicit: Docker Desktop and a host Docker install aren’t required, but the plugin provisions Docker Engine/Compose inside the managed machine (and builds that image on first use)? That distinction will help set expectations.

Updated based on your comment.

[jglogan]

Hi Robert, thank you for your contribution, but embedding docker/compose is not within the scope of this project. It requires far more effort to maintain than the k8s capability.

We've answered it in many prior issues, PRs, and discussion topics, but the TL;DR is that we'd prefer Compose to be an external plugin (see the work of @stephenlclarke, @Mcrich23, and others).