Compose
Caker compose lets you define and manage multi-VM environments from a compose.yml file, using a format compatible with Docker Compose.
For one or two development VMs tied to a repository, the lighter .cakerenv format (cakectl init/up/down) may be enough — see the comparison of the two formats.
Quick start
# Generate a template compose.yml in the current directory
cakectl compose init
# Edit compose.yml, then start all services
cakectl compose up
# Check status
cakectl compose ps
# Stop all services
cakectl compose down
# Remove all service VMs
cakectl compose rm --stop
The template compose init generates is a full two-VM example (MariaDB + phpMyAdmin, works on both arm64 and amd64), shipped inside Caker as a compose-template.yml file — MariaDB creates a dedicated MYSQL_USER/MYSQL_PASSWORD account for logging in to phpMyAdmin, and phpMyAdmin accepts any server or the one given by PMA_HOST — see “Packages”, “Extra files”, and “Post-install commands” below for how it installs each via packages/write_files/post_commands.
File lookup order
When -f is not specified, Caker looks for a compose file in the current directory in this order:
compose.ymlcompose.yamldocker-compose.ymldocker-compose.yaml
compose.yml format
name: myproject # project name — also used as VM name prefix
services:
app:
image: ubuntu:26.04 # cloud image; same syntax as cakectl build (or `alias:<id>`, see below)
ports:
- "3000:3000" # host:container[/proto] — TCP by default
- "8080:80/tcp"
sockets: # Caker extension: unix socket forwarding
- "/tmp/docker.sock:/var/run/docker.sock"
- "/tmp/host.sock:/tmp/guest.sock/udp"
volumes:
- ".:/workspace" # host:guest virtio-FS mount
environment: # injected into /etc/environment via cloud-init
- NODE_ENV=production
- DEBUG=1
networks:
- default # named network defined in the networks: section
depends_on:
- database # start database before app (list or condition map)
deploy:
resources:
limits:
cpus: "2" # vCPU count
memory: 2048M # RAM: M/MB, G/GB
hostname: app-host # guest hostname
restart: "no" # accepted but informational only (VMs, not containers)
# Caker VM extensions (not part of Docker Compose spec):
disk: 20 # root disk size in GiB (default 10)
user: ubuntu # guest username for exec/sh
password: ubuntu # guest password
nested: false # enable nested virtualisation
autostart: false # start this VM when caked starts
disk_format: raw # disk format (default: Caker's default format)
ifnames: true # predictable network interface names (default true)
dynamic_port_forwarding: false # dynamic port forwarding (default false)
ssh_authorized_key: ~/.ssh/id_ed25519.pub # SSH public key, or path to a file holding one
packages: # apt/dnf/apk/zypper packages installed via cloud-init at build
- git
- curl
write_files: # extra files written into the guest via cloud-init
- path: /etc/myapp/app.conf
content: "key = value" # inline text …
- path: /etc/myapp/from-host.conf
source: ./app.conf # … or a file read from the host (resolved like `volumes:`)
post_commands: # run after packages/write_files, via cloud-init
- systemctl enable --now docker
database:
image: ubuntu:26.04
environment:
POSTGRES_PASSWORD: secret
networks:
- default
deploy:
resources:
limits:
cpus: "2"
memory: 4096M
disk: 40
user: ubuntu
password: ubuntu
networks:
default:
driver: bridge # attaches the VM to a physical/bridged network — see "Networks" below
Service image (image)
image: takes the same references as cakectl build (ubuntu:26.04, a cloud image URL). Prefixed with alias:, it names an id of the VMImages.json catalog (cakectl aliases lists them), like cakectl build --alias: image: alias:alpine324. An unknown id makes compose up fail before the first VM is built; CPU and memory are raised to the catalog entry’s minimum, never lowering a higher value.
VM naming
Each service is provisioned as a VM named compose-<projectName>-<serviceName>. For example, a project named myproject with a service named app creates a VM called compose-myproject-app. You can inspect it with cakectl infos compose-myproject-app.
depends_on
Both short and long forms are supported:
# Short form
depends_on:
- database
# Long form (condition is accepted but not enforced — Caker starts in order regardless)
depends_on:
database:
condition: service_healthy
Memory syntax
deploy.resources.limits.memory accepts:
| Value | Meaning |
|---|---|
2048M / 2048MB |
2048 MiB |
2G / 2GB |
2048 MiB |
2048 |
2048 MiB (bare integer) |
Ports and volumes
ports: accepts host:guest[/tcp|udp|both] (or a single port, used on both sides); anything else — a host address (127.0.0.1:8080:80, host_ip: in the long form), a port range, an unknown protocol — is rejected with an error rather than silently turned into a different forward. An unparseable sockets: entry is rejected the same way; the host directory of a socket (for example ~/.docker/run) is created when it is missing.
volumes: accepts host:guest; Docker’s :ro (or read_only: true in the long form) makes the share read-only.
Networks
driver: bridge always attaches the VM to a real physical/bridged network — in Apple Virtualization.framework’s sense of “bridged,” not Docker’s own sense (a private, host-only virtual switch). Caker has no equivalent of Docker’s own “bridge” driver, so there is nothing to create here, only an existing interface to reference.
The target name resolves as follows:
- If the network declares a
name:field, that wins — typically paired withexternal: true, to point at an interface that already exists. - Otherwise, the network’s own key is used directly as a physical interface identifier (e.g.
en0) — Caker verifies that interface actually exists on the host and fails immediately if it doesn’t (compose upreturns a clear error instead of starting the VM with no network device). - Exception: the reserved key
default(Docker Compose’s own implicit-network convention — also whatcompose init’s own template uses) resolves to Caker’s configured default bridged interface (set undercaker→ Advanced Settings → “Bridged network”) — there’s no way to infer which host NIC a baredefaultnetwork should bridge to. An undeclareddefault(no top-levelnetworks:entry at all, or a baredefault:) resolves the same way, as Docker Compose’s implicit network.
When external: true, Caker just attaches the service VM to the already-existing interface, with no further validation.
Packages (packages)
A Caker VM extension: a list of packages (apt/dnf/apk/zypper, depending on the image’s distro) installed via cloud-init on the VM’s very first boot, before compose up considers it ready. Whenever packages: is set, Caker refreshes the package index first by default (see package_update below to turn that off) — without it, the install can fail against a stale or empty index on a freshly created image.
packages:
- git
- curl
package_update (another Caker VM extension) controls refreshing the package index before installing. By default it’s turned on automatically whenever packages: or package_upgrade: is set; an explicit value always wins, in both directions:
package_update: trueforces the refresh even with nopackages:— useful for a service that installs everything frompost_commands:(likephpmyadminin the templatecompose initgenerates), which would otherwise start from a stale index.package_update: falseturns off the implied refresh (a pre-populated local mirror, or a base image whose index is already fresh and where the round trip only slows the build down).
package_update: true
package_upgrade: true (another Caker VM extension, independent of packages:) upgrades every already-installed package on the image, not just the ones listed — unlike the index refresh, this is never turned on automatically: a full-system upgrade has a real cost (slower builds, a less reproducible image), so it’s opt-in.
package_upgrade: true
Extra files (write_files)
Another Caker VM extension: a list of files written into the guest via cloud-init on first boot. Each entry gives path: and exactly one of content: (inline text) or source: (a path read from the host, resolved the same way volumes:’s host side already is — relative to the current directory); permissions:, owner:, and append: are optional.
write_files:
- path: /etc/myapp/app.conf
content: "key = value"
permissions: "0644"
- path: /etc/myapp/from-host.conf
source: ./app.conf
append: true
A source: file that isn’t valid UTF-8 text is base64-encoded automatically (encoding: b64) instead of failing the build — so a small binary file works too.
Post-install commands (post_commands)
Another Caker VM extension: a list of shell commands run via cloud-init after packages are installed and files are written (cloud-init’s own runcmd always executes in the last boot stage, regardless of section order in the file).
post_commands:
- systemctl enable --now docker
- usermod -aG docker ubuntu
packages, write_files, post_commands, and environment all share the same cloud-init user-data document — they’re combined into one file at build time (including the /etc/environment file environment itself generates, merged into the same write_files: key as your own entries), so you can use them together without conflict.
Other VM extensions
A few more optional Caker VM extensions:
disk_format— the VM’s disk format (raw, etc.); defaults to Caker’s default format.ifnames— predictable network interface names inside the guest;trueby default.dynamic_port_forwarding— turns on dynamic port forwarding;falseby default.ssh_password_auth— allows SSH password authentication for the guest account (cloud-init’sssh_pwauth);falseby default, in which case only an SSH key can log in.ssh_authorized_key— an SSH public key (ssh-ed25519 AAAA…) or the path to a file holding one (~is expanded). A path is read and trimmed as soon as the file is loaded: a missing file makescompose upfail immediately, before any VM in the stack is built.
When user/password are omitted, the guest is created with admin/admin.
Subcommands
If
cakedis running as a service, usecakectl compose. If runningcakeddirectly (no service), usecaked compose.
compose up
Start (and create if needed) services in depends_on order.
cakectl compose up [-f <file> | -n <name>] [--wait-ip-timeout <seconds>] [services...]
caked compose up [-f <file> | -n <name>] [--wait-ip-timeout <seconds>] [services...]
| Flag | Default | Description |
|---|---|---|
-f, --file <path> |
auto-detect | Path to compose file |
-n, --name <name> |
— | Name of an already-registered project (see compose ls); used instead of the file |
--wait-ip-timeout <seconds> |
180 |
How long to wait for each VM’s IP before giving up |
[services...] |
all | Limit to specific named services |
If up is interrupted or partially fails, the successfully started VMs are recorded. Re-running compose up will not attempt to re-create VMs that already exist.
With -n/--name, up reads no file: it starts the already-registered project as it is, leaving its registered definition untouched. This is what the Start actions in Caker.app’s sidebar and menu bar do. The project must appear in compose ls, otherwise up fails with compose <name> not found.
The file up reads replaces the definition registered for that project, so a service added to the file since the last up is built and started. A VM that is already built is never rebuilt, though: its hardware, disk, network and cloud-init configuration are fixed when it is created. If such a service’s definition has changed, up only starts it and says so in its output — to apply the change, remove it (compose rm) and run compose up again. Likewise, a service removed from the file keeps its VM (which down/rm/ps no longer reach, since they walk the current definition) and up points that out.
compose down
Stop services in reverse depends_on order.
cakectl compose down [-f <file> | -n <name>] [--force] [services...]
caked compose down [-f <file> | -n <name>] [--force] [services...]
| Flag | Default | Description |
|---|---|---|
-f, --file <path> |
auto-detect | Path to compose file |
-n, --name <name> |
— | Name of an already-registered project (see compose ls); used instead of the file |
--force |
off | Force stop without graceful shutdown |
[services...] |
all | Limit to specific named services |
compose ps
Show status of services registered under this compose project.
The output lists the services (name, image, status); when the project isn’t registered or the call fails, it prints the failure reason instead.
cakectl compose ps [-f <file> | -n <name>] [services...]
caked compose ps [-f <file> | -n <name>] [services...]
| Flag | Default | Description |
|---|---|---|
-f, --file <path> |
auto-detect | Path to compose file |
-n, --name <name> |
— | Name of an already-registered project (see compose ls); used instead of the file |
[services...] |
all | Limit to specific named services |
compose rm
Remove (delete) service VMs and unregister the project.
cakectl compose rm [-f <file> | -n <name>] [--stop] [--force] [services...]
caked compose rm [-f <file> | -n <name>] [--stop] [--force] [services...]
| Flag | Default | Description |
|---|---|---|
-f, --file <path> |
auto-detect | Path to compose file |
-n, --name <name> |
— | Name of an already-registered project (see compose ls); used instead of the file |
--stop |
off | Stop running services before removing |
--force |
off | Force stop without graceful shutdown (only has an effect with --stop) |
[services...] |
all | Limit to specific named services |
compose ls
List all registered compose projects and their service status.
cakectl compose ls
This command does not need a compose file — it reads the global project registry.
compose edit
Rebuilds a registered project’s definition from the registry (compose.json), opens it in $VISUAL/$EDITOR (vi by default) and, if it changed, applies it with compose up (the edited definition replaces the registered one). The registry does not keep the original compose.yml, so comments and formatting are not restored.
cakectl compose edit [-o <path>] [--wait-ip-timeout <seconds>] <name>
caked compose edit [-o <path>] [--wait-ip-timeout <seconds>] <name>
| Option | Default | Description |
|---|---|---|
-o, --output <path> |
none | Write the definition to this file instead of editing it (nothing is applied) |
--wait-ip-timeout <seconds> |
180 | Max time to wait for the IP |
<name> |
required | Name of the registered project |
The project name cannot change. If the edit is invalid, the error names the temporary file where it was kept. cakectl compose edit asks a caked that returns the registered definition; against an older caked it fails rather than apply a partial reconstruction.
compose init
Write a commented compose.yml template in the current directory.
cakectl compose init [--force]
caked compose init [--force]
| Flag | Default | Description |
|---|---|---|
-f, --force |
off | Overwrite an existing compose.yml |
compose library
A library of compose.yml templates for what developers set up most often. Each template is a plain .yml file that is easy to read and edit. The library ships with Caker (the compose-library folder, like VMImages.json for images) and library sync updates it from the main branch of the GitHub repository into <CAKE_HOME>/compose-library/, which then takes precedence over the bundled copy; the files in that folder can be edited by hand (the next sync overwrites the ones it downloads, and leaves the ones you added). Until the templates are published on main, the sync says so and the bundled copy stays in use.
These commands work on the machine they are typed on and never go through caked: clone writes the compose.yml into your directory, where compose up reads it.
cakectl compose library [list] [-c category] [words…] [--format text|json]
cakectl compose library show <id> [--format text|json]
cakectl compose library clone <id> [-n name] [-o path] [-f]
cakectl compose library sync [--format text|json]
caked compose library … # same subcommands
| Subcommand | Description |
|---|---|
list |
List the templates; -c filters by category, words filter on the id, name, summary, category and tags |
show <id> |
Print a template’s compose.yml, to read it before cloning it |
clone <id> |
Write the template as compose.yml in the current directory (-o: file or directory; -f: overwrite). -n renames the project, including the compose DNS names services use to find each other (db.lamp.compose.internal) |
sync (alias update) |
Update the library from GitHub. A downloaded library is only installed when every template is valid |
Bundled templates:
| Id | Category | What it is |
|---|---|---|
docker-host |
Containers | An Ubuntu VM running the Docker engine and the compose plugin, with the default user in the docker group; ports 8080 and 8443 and the Docker socket are forwarded to the host. |
k3s |
Containers | A single-node k3s cluster; the Kubernetes API is forwarded to the host on port 6443, and the ingress (Traefik) on 8080 and 8443. |
mariadb-phpmyadmin |
Database | A MariaDB server and a phpMyAdmin web UI on a second VM that finds it through compose DNS. |
postgres |
Database | PostgreSQL from the Ubuntu archive, listening on every interface with an application role and database. |
redis |
Database | Redis from the Ubuntu archive, reachable from the host and from the other VMs, protected by a password. |
ubuntu-dev |
Development | A single Ubuntu 26.04 VM with the usual build tools, Git and Python ready to use; ports 3000 and 8000 are forwarded to the host for dev servers. |
gitea |
Development | A self-hosted Git forge (Gitea with SQLite and its built-in SSH server); the web UI is forwarded on 3000 and Git over SSH on 2222. |
rabbitmq |
Messaging | RabbitMQ with the management UI; AMQP is forwarded on 5672 and the web console on 15672. |
vaultwarden-caddy |
Security | A Vaultwarden password manager (Bitwarden-compatible) on one VM and a Caddy reverse proxy with a local HTTPS certificate on another; HTTPS is forwarded on 8443. |
garage |
Storage | A single-node Garage object store with an S3-compatible API, a bucket and an access key created at first boot; the S3 API is forwarded on 3900 and the admin API on 3903. |
ansible-lab |
DevOps | An Ansible control node with two managed Ubuntu nodes, an inventory using compose DNS names and a sample playbook that installs nginx. |
k3s-cluster |
Containers | A k3s control-plane VM and two agent VMs that join it through compose DNS; the API is forwarded on 6443, the ingress on 8080 and 8443. |
prometheus-grafana |
Monitoring | Prometheus and Grafana on one VM scraping node_exporter on itself and on two other VMs; Prometheus is forwarded on 9090 and Grafana on 3000. |
postgres-patroni |
Database | Two PostgreSQL nodes managed by Patroni with an etcd store, and an HAProxy VM that routes port 5000 to the primary (5001 to the replicas, 7000 for its status page). |
nextcloud |
Storage | A Nextcloud file-sync and collaboration server from the official snap, with an administrator account; the web UI is forwarded on 8080. |
lamp |
Web | Apache with PHP on one VM and MariaDB on another, wired together through compose DNS. |
lemp |
Web | Nginx with PHP-FPM on one VM and MariaDB on another, wired together through compose DNS. |
nodejs-redis |
Web | A small Node.js HTTP app (hit counter) running as a systemd service, backed by a Redis VM. |
python-postgres |
Web | A small Flask app (hit counter) running as a systemd service, backed by a PostgreSQL VM. |
alpine-dev |
Development | A single Alpine Linux 3.24 VM with the usual build tools, Git and Python ready to use; ports 3000 and 8000 are forwarded to the host for dev servers. |
docker-host-alpine |
Containers | An Alpine Linux VM running the Docker engine and the compose plugin, with the default user in the docker group; ports 8080 and 8443 and the Docker socket are forwarded to the host. |
redis-alpine |
Database | Redis from the Alpine repositories, reachable from the host and from the other VMs, protected by a password. |
postgres-alpine |
Database | PostgreSQL 18 from the Alpine repositories, listening on every interface with an application role and database. |
lemp-alpine |
Web | Nginx with PHP-FPM on one Alpine VM and MariaDB on another, wired together through compose DNS. |
prometheus-grafana-alpine |
Monitoring | Prometheus and Grafana on one Alpine VM scraping node_exporter on itself and on two other VMs; Prometheus is forwarded on 9090 and Grafana on 3000. |
The *-alpine templates are the Alpine Linux 3.24 counterparts of Ubuntu stacks (image: alias:alpine324, the VMImages.json catalog’s cloud image, resolved for the host’s architecture; linuxcontainers.org’s images:alpine image has no cloud-init): apk packages, OpenRC services (rc-service, rc-update), an alpine account and the musl C library. They are written from the contents of the Alpine packages and have not been booted on a VM.
Templates that serve something forward their ports to the host with ports: (PostgreSQL 5432, Redis 6379, RabbitMQ 5672/15672, the web stacks 8080 or 3000, the k3s Kubernetes API 6443 and its ingress 8080/8443, docker-host’s 8080/8443 for published containers, ubuntu-dev’s 3000/8000 for dev servers, Gitea’s 3000 and 2222 for Git over SSH, Nextcloud’s 8080, Vaultwarden behind Caddy on HTTPS 8443, Garage’s S3 API 3900 and admin API 3903). docker-host also forwards the guest’s Docker socket to ~/.docker/run/docker.sock on the host with sockets:, so export DOCKER_HOST=unix://$HOME/.docker/run/docker.sock is all the Mac’s docker client needs to drive the VM’s engine (that access is root-equivalent inside the VM). Caker creates the socket’s directory when it is missing; the path is also Docker Desktop’s, so don’t run both together.
The templates are starting points that have not been booted on a machine of every family: read one before compose up, it installs packages and runs commands in the new VMs. To add a template, see Development.
Caker app (GUI)
Beyond the CLI, the caker app offers full Compose management in its own interface — available in every connection mode, including .app (VMs embedded in-process, no separate caked), since the Compose logic has no server-process dependency at all.
- “Compose” sidebar category — lists every registered project (polled every 3 seconds; there’s no push-notification mechanism for Compose state). Each row shows a summary (“n/m running”), a status indicator, and offers Edit / Start-or-Stop / Delete once selected. A detail pane shows each service’s individual status.
- Compose Editor — a raw-YAML editor rather than a fully structured form (the format’s polymorphic richness — short/long forms for
depends_on/environment/ports/volumes— would make a complete structured form out of proportion for a first pass). Seeded from the default template for a new project, or the registered definition of an existing one for editing (the originalcompose.ymland its comments are not kept; against an oldercakedonly each service’s name and image are restored). A live “Parses OK” / “Parse error: …” indicator updates as you type; “Save & Start” simply re-runscompose upwith the edited definition: new services are built, services whose VM already exists are only started (seecompose up). A small “Add service” form inserts a formatted YAML block for a quick addition without hand-editing the raw YAML. - Template library — the toolbar’s “Library” button (and “Browse the template library” when the list is empty) opens the library: search, category filter, YAML preview, “Use template” (opens the Compose Editor pre-filled) or “Save as…”, and “Sync” to update it from GitHub.
- Menu bar extras — a “Compose” submenu lists registered projects with per-project Open/Start/Stop actions, plus a “New compose project…” item that opens the editor directly.
DNS resolution between services
A service can reach another service in the same project by name, at <service>.<project>.compose.internal (e.g. mariadb.myapp.compose.internal) — no need to hand-copy an IP into environment:. Any VM, not just compose services, is also resolvable by its plain name: <vmname>.compose.internal (e.g. myvm.compose.internal) works for any running VM, whether or not it belongs to a compose project. caked runs a small DNS resolver bound to the gateway address of the shared default network (the one passed to caked networks run) — the network every VM already has, regardless of its OS or its primary driver: — and it answers for that synthetic domain itself. In the direct-download build it is also the main DNS server of the network: DHCP hands the gateway out as DNS server (port 53), and every name outside the synthetic domain is forwarded to the host’s own resolvers (/etc/resolv.conf, minus loopback and the gateway) and the answer relayed back. A name inside the domain that nobody registered gets NXDOMAIN locally, never forwarded. At most 64 forwarded queries are in flight at once; past that the resolver answers SERVFAIL immediately. Forwarding is UDP only (no TCP retry for a truncated answer). With the App Store build, or any network that stays on vmnet’s DHCP, the resolver only answers for the synthetic domain and refuses the rest, and the guest setup routes just that domain to it.
The domain (compose.internal by default) is configurable in Caker.app, under Advanced Settings → “Compose” section → “Domain” field. Only virtual machines built after the change pick up the new domain — an already-provisioned VM keeps using the domain it was built with until rebuilt.
The resolver belongs to the network. There is no caked dns process to start any more: every shared network with DNS enabled (--dns on networks create/configure, the “Enable DNS” toggle in Caker.app) runs its own resolver, bound to that network’s gateway address, for as long as the network runs. The default network (default, 192.168.32.0/24 unless changed in Advanced Settings → “Default network”, applied on next restart) always has it on. That network is a shared network without isolation (it replaces Apple’s NAT network), so VMs can reach each other. The old names nat and NAT shared network are converted to default automatically. In a compose file networks: [default] is still Docker’s implicit network (the default bridged interface); use networks: [nat] for the shared network.
DHCP. In the direct-download build, caked serves DHCP itself on the networks it runs as root (shared and host networks, macOS 26 and later): vmnet’s own DHCP server is switched off and each network runs its own DHCP server with its own lease table, <CAKE_HOME>/net/<network>/dhcpd_leases (same format as vmnet’s /var/db/dhcpd_leases). Leases of different networks are therefore independent, the network’s --dhcp-lease is its lease time, and the pool runs from the address after the gateway to --dhcp-end. The server reads the network’s bridge with BPF rather than binding UDP 67 (macOS keeps a launchd-owned socket on that port), so it needs root and starts as soon as the first VM attaches to the network. Set CAKED_VMNET_DHCP=vmnet to keep vmnet’s DHCP on a network. Bridged networks, non-root runs, macOS 15 and the App Store build keep vmnet’s DHCP.
Guest configuration. In the direct-download build there is none: DHCP gives the guest the gateway as DNS server and the compose domain as search domain. In the App Store build (sandboxed: no root, no embedded DHCP server) the guest is configured from the inside instead, by the agent install script or the post_boot_command of the bundled Linux PackerLite templates: a systemd-resolved drop-in that routes only this domain to the gateway (port 28053) or, on Alpine, a local dnsmasq. The direct-download build also applies this in-guest wiring when the host leaves the networks on vmnet’s DHCP (macOS 15, CAKED_VMNET_DHCP=vmnet), decided when the guest is built; a bridged network has no resolver. Only VMs built after a change of domain or gateway address pick it up.
Limits. Verified on live vmnet networks with a simulated guest (DHCP lease, local name, forwarded name through the gateway on port 53) but not yet with a real pair of VMs; the App Store build’s guest configuration has not been run in the sandbox; minimal images without systemd-resolved (some Debian/EL) are configured on a best-effort basis there. A client’s DHCP hostname is stored only if it is a valid host name (letters, digits, -, ., _, up to 63 bytes).
For the full mechanism, and the one caveat worth knowing (VM-to-VM traffic on the default network is reasoned from code, not yet verified end to end with a real two-VM boot), see the “Compose DNS” section of CLAUDE.md.
Differences from Docker Compose
| Feature | Docker Compose | Caker compose |
|---|---|---|
| Runtime | Container daemon | Apple Virtualization.framework VMs |
| VM extensions | No | disk, disk_format, user, password, nested, autostart, ifnames, dynamic_port_forwarding, ssh_authorized_key, ssh_password_auth, sockets, packages, package_update, package_upgrade, write_files, post_commands |
restart |
Enforced policy | Accepted, not enforced |
deploy.replicas, deploy.resources.reservations |
Enforced | Accepted, not applied — one VM per service, only limits are used |
depends_on conditions |
Enforced | Order only — conditions are accepted but not checked |
build: key |
Build from Dockerfile | Not supported — use image: with a cloud image URL or simplestream alias |
| Named volumes | Managed by Docker | Not supported — use bind mounts in volumes: |
--detach |
Background | Always in background (VMs are long-lived) |
ls |
Lists containers | Lists registered compose projects |
Examples
Start a two-VM stack
# Initialise
cd myproject
cakectl compose init
# Edit compose.yml…
cakectl compose up
Start only one service
cakectl compose up app
Rebuild from a custom file path
cakectl compose up -f ./infra/staging.yml
Inspect a service VM directly
cakectl infos compose-myproject-app
cakectl exec compose-myproject-app -- uname -a
Tear down and clean up
# Stop services (keep VMs)
cakectl compose down
# Stop and delete VMs, remove project from registry
cakectl compose rm --stop
List all compose projects
cakectl compose ls