At a very abstract level, the Ambient architecture is as follows:
- Ambient creates a virtual machine with four block devices (using
virtio_blk) in addition to the system disk (/dev/vdaon Linux):/dev/vdb: the read-only source device: a tar archive of the project’s source tree/dev/vdc: the read/write artifact device: for the project to write a tar archive of any build artifacts it wants to export- this would be write-only if that was possible
- when the build starts, this contains only zeroes
- after the build a tar archive is extracted from this
/dev/vdd: the read-only dependencies device: a tar archive of additional dependencies in a form that the project can use/dev/vde: the read/write cache device: a tar archive of any files the project wants to persist across runs; for example, for a Rust project, this would contains the cargo target directory contents- when a build starts, this can be empty; the build must deal with an empty cache
- The VM additionally has a serial port where it will write the build log. On Linux this is
/dev/ttyS0. - The VM automatically, on boot, creates
/workspace/{src,cache,deps}, and extracts the source, cache, and dependencies tar archives to those directories. - The VM then changes current working directory to
/workspace/srcand runs./.ambient-script(if the script isn’t executable, the VM first makes it so). The script’s stdout and stderr are redirected to the serial port.
Data is transferred out of the VM as tar archives instead of disk images with file systems, to allow the data to be unpacked with user space tooling only. Mounting a disk image in a way that involves the kernel is risky. For example, an ext2/3/4 file system can tell the kernel to panic if there’s is corruption, and the CI run can corrupt the file system on purpose. See for example https://infosec.exchange/@wdormann/113625346544970814.
The ambient-build.service and ambient-run-script files in the Ambient source tree implement this for Linux with systemd, and have been tested with Debian.