Spec reference

A spec is one YAML file at the root of a project: isoloom.yml (isoloom.yaml also works, but not both). Unknown fields are errors, so a typo never passes silently.

Top level

version: 1                 # required, the format version
name: invoice-portal       # required, kebab-case
networks: { … }            # required, at least one
reach: [ … ]               # optional, traffic allowed between networks
inputs: [ … ]              # optional, launch-time values
machines: { … }            # required, at least one
checks: [ … ]              # optional, black-box checks
targets: [ … ]             # optional, narrows the derived targets

Field	Type	Notes
`version`	integer	Must be `1`.
`name`	string	Kebab-case: lowercase letters, digits, dashes.
`networks`	map	Network name → network. Names are DNS labels.
`reach`	list	Allowed traffic between networks; see below.
`inputs`	list	`UPPER_SNAKE_CASE` names of values provided at launch.
`machines`	map	Machine name → machine, in start order. Names are DNS labels.
`checks`	list	Paths of check scripts in the project.
`targets`	list	Subset of the derived targets to keep.

Networks

networks:
  dmz:      { cidr: 10.30.10.0/24 }
  internal: { cidr: 10.30.20.0/24, internet: false }

Field	Type	Default	Notes
`cidr`	string		A network address inside `10.0.0.0/8`, sized `/24` to `/29`. Networks can't overlap.
`internet`	bool	`true`	Whether machines on it may reach the internet.
`gateway`	string		A machine that routes this network with its own rules (an edge firewall). It must be on the network at the gateway address. See Networks and gateways.

Addresses stay inside 10.0.0.0/8 because Docker's default pools and most home networks use 172.16.0.0/12 and 192.168.0.0/16. On every network, .1 is reserved for the gateway (only the network's gateway machine may take it) and the last address (e.g. .254) for the router.

Reach

Machines on the same network always reach each other. Between networks, everything is blocked except what reach: allows:

reach:
  - { from: access, to: dmz }                         # every port
  - { from: dmz, to: internal, ports: [8080, 5432] }  # only these ports

Field	Type	Notes
`from`, `to`	string	Network names. Must differ.
`ports`	list of integers	Empty means every port.

Each target enforces these rules with its own mechanism; see Networks and gateways.

Inputs

inputs: [API_URL, LAUNCH_TOKEN]

Names of values a runner provides at launch. A machine receives only the inputs it lists.

Machines

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 below.
`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.
`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).

`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-2022`, `windows-11`. Each target maps it to its own image.
`provision`	list	Steps run inside the VM, in order: shell scripts, Ansible playbooks, PowerShell. Required except on the access machine.

Checks

checks:
  - checks/portal-answers.sh
  - checks/internal-is-blocked.sh

Scripts run on the environment's networks. See Checks.

Targets

targets: [docker, vagrant]

Keeps only these of the derived targets. Values: docker, hosted, cloud-docker, vagrant, proxmox, cloud-vm, ludus. See Targets.