Caker

Virtualization platform for macOS

View project on GitHub

.cakerenv environments

A .cakerenv file describes, in YAML, the development VM(s) a project needs. Kept at the project root (much like a Vagrantfile), it lets anyone recreate that environment with one command: cakectl up creates the VMs that don’t exist yet and starts the others, cakectl down stops them.

It is Caker’s lightest-weight, per-directory environment format. For a fuller multi-VM stack (Docker Compose–compatible format, project registry, ps/rm/ls, GUI, DNS between services), use Compose instead — see Choosing between .cakerenv and Compose below.

Quick start

cd ~/src/myproject

# Write a commented .cakerenv template in the current directory
cakectl init

# Edit .cakerenv, then create/start every VM
cakectl up

# Stop every VM, in reverse dependency order
cakectl down

The same commands exist on the caked side (caked init, caked up, caked down); they act on the local machine directly, without going through the daemon — see Commands.

Commands

Command Purpose
init [-f/--force] Write the .cakerenv template into the current directory. Refuses to overwrite an existing file without --force.
up [-f/--env-file <path>] [--wait-ip-timeout N] [vm...] Create missing VMs and start the others, in depends-on order. With no arguments, every VM in the file. --wait-ip-timeout (default 180 s) bounds the wait for each VM’s IP address.
down [-f/--env-file <path>] [--force] [vm...] Stop VMs in reverse depends-on order. --force stops without waiting for a graceful shutdown.

up and down read .cakerenv from the current directory, or the file given with -f/--env-file (which can have any name). There is no ps or rm: use cakectl list, cakectl infos <vm> and cakectl delete <vm>.

cakectl up/down go through the caked daemon over gRPC; caked up/down do the same work locally (useful when the daemon isn’t running, or in a script on the host).

File format

The file comes in two shapes.

Single-VM mode

Every field sits at the top level of the file, which describes one VM.

name: myapp            # optional: defaults to the current directory name
image: ubuntu:24.04
cpus: 2
memory: 2048           # MiB
disk: 20               # GiB
ports:
  - "3000:3000"
mounts:
  - "~/src/myapp:/workspace"

The VM’s name is, in order: the name: field, otherwise the name of the current directory (the one the command runs from, even with --env-file).

Multi-VM mode

A vms: map whose keys are VM names and whose values are VM specs. As soon as vms: is present and non-empty, every top-level field is ignored, name: included.

vms:
  app:
    image: ubuntu:24.04
    cpus: 2
    memory: 2048
    ports:
      - "3000:3000"
    depends-on:
      - database

  database:
    image: ubuntu:24.04
    memory: 4096
    disk: 40

The key is used as-is as the VM name (app, database) — no prefix, unlike Compose, which names its VMs compose-<project>-<service>. See Limitations.

VM fields

The same fields work at the top level (single-VM mode) or under each vms: entry. Only depends-on is specific to multi-VM mode.

Field Type Default Description
image string Ubuntu 24.04 LTS cloud image Image source, same syntax as cakectl build: ubuntu:24.04 (the ubuntu simplestreams remote), an https://… cloud-image URL, oci://…, template://…, etc. A local path is only accepted by caked up.
cpus integer 2 Number of vCPUs.
memory integer 2048 Memory in MiB (a bare number, no M/G suffix).
disk integer 10 Root disk size in GiB.
ports list none Host → guest port forwards. See String formats.
sockets list none Host → guest Unix socket forwards.
mounts list none Virtio-FS directory shares. Nothing is shared by default.
networks list NAT only Additional network interfaces. Every VM always gets a NAT interface, even with an empty list.
cloud-init string (block) none Inline cloud-init user-data, see cloud-init.
autostart boolean false Start the VM when caked starts.
nested boolean false Enable nested virtualization (silently turned off if the host doesn’t support it).
depends-on list none Names of other VMs in the same file to start before this one (multi-VM mode only).
user string admin Name of the account created in the guest when the VM is built.
password string admin That account’s password.

The disk format isn’t configurable: it is Caker’s default format for the platform. Unknown keys are ignored without an error — a typo in a field name produces no message.

String formats

Field Syntax Examples
ports host:guest[/proto] — proto: tcp (default), udp or both "3000:3000", "8053:53/udp"
sockets host_path:guest_path[/proto] — same proto as ports "/tmp/docker.sock:/var/run/docker.sock"
mounts source[:destination][,ro][,name=…][,uid=…][,gid=…] "~/src/myapp:/workspace", "~/data:/data,ro"
networks network[,mode=…][,mac=…] — mode: auto or manual nat, bridged, en0, a network from cakectl networks list
  • ports: only the host:guest[/proto] form is supported. Unlike Compose, .cakerenv doesn’t validate ports: an IP prefix (127.0.0.1:8080:80) or a range (3000-3005:3000-3005) is misread, and an unparseable entry is dropped silently.
  • mounts: read-only is written ,ro; Docker’s :ro form is not recognized (the :ro is lost and the share stays read-write).
  • Relative paths: with cakectl up, a mount’s source path is resolved in the caked daemon’s working directory, not your shell’s. Use absolute or ~/… paths (the generated template contains ".:/workspace", which only works as intended with caked up).

cloud-init

cloud-init: | holds a cloud-config document (without a #cloud-config header — Caker adds it). It is merged with the configuration Caker generates (account, SSH key, agent): lists such as packages or runcmd are appended to it.

vms:
  app:
    image: ubuntu:24.04
    cloud-init: |
      package_update: true
      packages:
        - nodejs
        - git
      runcmd:
        - echo "ready" > /etc/motd

The content is written to a temporary file and passed as user-data, exactly like cakectl build --cloud-init <file>. It only applies when the VM is created.

Start order and depends-on

  • up starts VMs in the topological order given by depends-on; beyond that constraint, VMs are processed in alphabetical order (or in the order of the names passed as arguments). down uses the reverse order.
  • A dependency on a VM that isn’t in the file, or a cycle, fails the command before anything is done.
  • An unknown VM name passed as an argument (cakectl up typo) is an error.
  • Filtering doesn’t pull in dependencies: cakectl up app starts only app, even if app depends on database (unlike docker compose up app). The order only applies between the VMs you asked for: cakectl up app database does start database first, then app. Likewise, cakectl down database doesn’t stop app.
  • depends-on is about order only: up waits for each VM’s IP address before moving on to the next one, not for an application inside it to be ready.

up on an existing VM

up only creates a VM when no VM with that name exists. For an existing VM:

State cakectl up caked up
stopped started started
running “already running” waits for its IP and reports it
paused message suggesting cakectl start <vm> a start is attempted, no special handling

An existing VM is never reconfigured or rebuilt: changing cpus, memory, ports, mounts, cloud-init… in .cakerenv has no effect on a VM that already exists. To apply the change, use cakectl configure <vm> …, or delete the VM (cakectl delete <vm>) and run cakectl up again.

Choosing between .cakerenv and Compose

  .cakerenv Compose
File .cakerenv (or -f) compose.yml, compose.yaml, docker-compose.yml…
Format Caker-specific, minimal Docker Compose–compatible (+ VM extensions)
Commands init, up, down init, up, down, ps, rm, ls
VM names the key (app) compose-<project>-<service>
Project registry no yes (compose ls, Caker.app’s Compose pane)
Guest customization raw cloud-init block packages, environment, write_files, post_commands…
Networks attached as written networks: section validated by up
GUI no (CLI only) yes

Pick .cakerenv for one or two development VMs tied to a repository; pick Compose as soon as you need to track a stack’s state or drive it from Caker.app.

Limitations

  • Names aren’t isolated: VMs get exactly the name written in the file. If a VM named app already exists (created by hand or by another .cakerenv), up starts it instead of creating one, and down stops it.
  • Existing VMs aren’t reconfigured (see above).
  • With cakectl up, the image must be remote (no local path) and relative mount paths are resolved on the daemon side.
  • Unknown keys and unparseable ports/sockets entries are ignored without an error.

See also