.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 thehost:guest[/proto]form is supported. Unlike Compose,.cakerenvdoesn’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:roform is not recognized (the:rois lost and the share stays read-write).- Relative paths: with
cakectl up, a mount’s source path is resolved in thecakeddaemon’s working directory, not your shell’s. Use absolute or~/…paths (the generated template contains".:/workspace", which only works as intended withcaked 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
upstarts VMs in the topological order given bydepends-on; beyond that constraint, VMs are processed in alphabetical order (or in the order of the names passed as arguments).downuses 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 appstarts onlyapp, even ifappdepends ondatabase(unlikedocker compose up app). The order only applies between the VMs you asked for:cakectl up app databasedoes startdatabasefirst, thenapp. Likewise,cakectl down databasedoesn’t stopapp. depends-onis about order only:upwaits 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
appalready exists (created by hand or by another.cakerenv),upstarts it instead of creating one, anddownstops 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/socketsentries are ignored without an error.
See also
- Compose — multi-VM stacks in Docker Compose format
- Command Summary —
build/launchoptions (--publish,--mount,--network,--cloud-init) - Cheat Sheet