Machines

A machine is something the environment runs: its addresses, what answers on it, and how a container or a VM produces it. Machines start in the order written, after what they depend on.

machines:
  web:
    networks: { app: 31 }
    services: [{ port: 8080, name: portal, http: true }]
    inputs: [API_URL]
    resources: { cpus: 2, memory_mb: 2048, disk_gb: 20 }
    depends_on: [database]
    docker:
      build: build/web
    vm:
      os: debian-12
      provision: [provision/web.sh]

Field	Type	Notes
`networks`	map	Network name → last octet of the machine's address on it. At least one.
`services`	list	What answers on the machine; see Services.
`inputs`	list	Range inputs this machine receives. Each must be declared at the top level.
`resources`	object	`cpus`, `memory_mb`, `disk_gb`. Defaults: 1 CPU, 1024 MB, 20 GB.
`depends_on`	list	Machines that must answer before this one starts. They need at least one service. No cycles.
`volumes`	map	Data that survives restarts and re-creation of the machine, until the environment is destroyed: a name → an absolute path, e.g. `{ data: /var/lib/postgresql/data }`. A named volume on Docker; the VM's own disk on VMs. Not shared between machines yet.
`access`	bool	The machine a user lands on. At most one. May have no implementation.
`docker`	object	Container implementation.
`vm`	object	VM implementation.

Every machine except the access machine needs at least one implementation.

Services

Field	Type	Notes
`port`	integer	1 to 65535, unique on the machine.
`name`	string	Optional label.
`http`	bool	Whether it speaks HTTP (used by tools that open it in a browser).
`publish`	integer	Also reachable from the user's machine on this port, on its loopback (127.0.0.1) only: Docker publishes it, Vagrant forwards it. Unique across the environment.

`docker:`

Field	Type	Notes
`image`	string	A published image.
`build`	string	A build folder in the project.
`init`	list	One-shot jobs (scripts or folders) that run before the machine counts as ready, e.g. seeding a database.

Use exactly one of image and build.

`vm:`

Field	Type	Notes
`os`	string	One of `debian-12`, `ubuntu-24.04`, `kali`, `windows-server-2019`, `windows-server-2022`, `windows-11`. Each target maps it to its own image; Windows Server 2022 and Windows 11 need `image` for now.
`provision`	list	Steps run in the VM, in order: `.sh` scripts and Ansible playbooks (`.yml`, run inside the VM) on Linux; `.ps1` scripts on Windows, each uploaded and run on its own. Optional when the environment has environment-level provisioning.
`image`	object	The machine's own image instead of the built-in one for `os`: `vagrant` (a box name) and `vagrant_version`.

Windows

Windows machines (windows-server-2019 today) are reached over WinRM with the box's own account, and provisioned in PowerShell. Since Ansible can't run on Windows itself, an Ansible setup for Windows machines uses environment-level provisioning, from a controller. Not on Windows yet: routes between networks, internet: false and volumes. isoloom generate says so instead of writing a file that wouldn't work.