AutomataOS

A NixOS-based operating system image with a pre-configured Automata deployment for on-premises and edge computing.

Overview

AutomataOS combines:

k3s single-node cluster for container orchestration
Automata deployment from the pinned v0.2.12-ce Automata source tree
PostgreSQL via Helm chart
Temporal workflow orchestration
cert-manager for certificate provisioning
Traefik via the bundled k3s integration

Build Support

Supported build targets:

x86_64-linux
aarch64-linux

Supported host architectures:

x86_64 / amd64
aarch64 / arm64

Supported build paths:

Native Nix builds for host-native workflows
Docker builds for portable, containerized builds
Podman builds for portable, containerized builds

Supported output packages:

automata-image for the existing VM runner bundle
automata-iso for a bootable ISO you can write to USB media or mount in QEMU
automata-qcow-efi for a QEMU-ready qcow2 disk image
automata-raw-efi for a raw EFI disk image you can flash to USB storage

make build and ./scripts/build.sh choose a default Linux target from the host CPU architecture:

x86_64 / amd64 hosts default to x86_64-linux
aarch64 / arm64 hosts default to aarch64-linux

If your host does not have a local Nix setup that can build the selected Linux target, use the Docker or Podman flow instead.

Project Structure

automataos/
├── flake.nix             # Nix flake entry point
├── flake.lock            # Locked dependencies, including Automata tag pin
├── Containerfile.build   # Containerized builder for Docker and Podman
├── Makefile              # Build, run, and maintenance commands
├── modules/
│   ├── automata.nix      # Automata + k3s + Helm deployment config
│   └── qemu-guest.nix    # QEMU guest support and image import
├── scripts/
│   ├── build.sh          # Native build helper with target selection
│   └── run-vm.sh         # Run a built VM with host CPU settings
└── README.md

Quick Start

Prerequisites

Nix with flakes enabled for native builds
Docker or Podman for containerized builds
QEMU for VM testing
4 GB+ RAM recommended
20 GB+ disk space recommended

Native Builds

Build the host-native target:

nix build

Build an explicit target:

nix build .#packages.x86_64-linux.automata-image
nix build .#packages.aarch64-linux.automata-image
nix build .#packages.x86_64-linux.automata-iso
nix build .#packages.x86_64-linux.automata-qcow-efi
nix build .#packages.aarch64-linux.automata-raw-efi

Use the helper script:

./scripts/build.sh
TARGET_SYSTEM=x86_64-linux ./scripts/build.sh
TARGET_SYSTEM=aarch64-linux ./scripts/build.sh
TARGET_PACKAGE=automata-iso ./scripts/build.sh
TARGET_PACKAGE=automata-qcow-efi ./scripts/build.sh
TARGET_PACKAGE=automata-raw-efi ./scripts/build.sh

Containerized Builds

Docker and Podman run the same flake build inside nixos/nix:latest and map each target to the matching container platform:

x86_64-linux -> linux/amd64
aarch64-linux -> linux/arm64

make build-docker and make build-podman validate the selected flake output inside the builder image. They do not create a host-side ./result symlink by themselves.

Build with Docker:

make build-docker TARGET_SYSTEM=x86_64-linux
make build-docker TARGET_SYSTEM=aarch64-linux

Build with Podman:

make build-podman TARGET_SYSTEM=x86_64-linux
make build-podman TARGET_SYSTEM=aarch64-linux
make build-podman TARGET_SYSTEM=x86_64-linux TARGET_PACKAGE=automata-iso
make build-podman TARGET_SYSTEM=x86_64-linux TARGET_PACKAGE=automata-qcow-efi
make build-podman TARGET_SYSTEM=aarch64-linux TARGET_PACKAGE=automata-raw-efi

Export a real disk image from the Podman build into dist/:

make export-podman-iso TARGET_SYSTEM=x86_64-linux
make export-podman-iso TARGET_SYSTEM=aarch64-linux
make export-podman-qcow-efi TARGET_SYSTEM=x86_64-linux
make export-podman-qcow-efi TARGET_SYSTEM=aarch64-linux
make export-podman-raw-efi TARGET_SYSTEM=x86_64-linux
make export-podman-raw-efi TARGET_SYSTEM=aarch64-linux

Run the raw container commands directly:

docker build --platform linux/amd64 --build-arg TARGET_SYSTEM=x86_64-linux --build-arg TARGET_PACKAGE=automata-qcow-efi -f Containerfile.build .
docker build --platform linux/arm64 --build-arg TARGET_SYSTEM=aarch64-linux --build-arg TARGET_PACKAGE=automata-raw-efi -f Containerfile.build .

podman build --platform linux/amd64 --build-arg TARGET_SYSTEM=x86_64-linux --build-arg TARGET_PACKAGE=automata-qcow-efi -f Containerfile.build .
podman build --platform linux/arm64 --build-arg TARGET_SYSTEM=aarch64-linux --build-arg TARGET_PACKAGE=automata-raw-efi -f Containerfile.build .

Makefile Commands

make help                          # Show all available commands
make build                         # Build host-native Linux target
make build-x86_64                  # Build x86_64-linux image
make build-aarch64                 # Build aarch64-linux image
make build-iso                     # Build a bootable ISO image
make build-qcow-efi                # Build a QEMU-ready qcow2 disk image
make build-raw-efi                 # Build a raw EFI disk image for USB flashing
make build-docker                  # Build in Docker
make build-podman                  # Build in Podman
make export-podman                 # Copy the selected Podman-built artifact to dist/
make export-podman-iso             # Build/export an ISO image to dist/
make export-podman-qcow-efi        # Build/export a qcow2 image to dist/
make export-podman-raw-efi         # Build/export a raw EFI image to dist/
make dry-run                       # Dry-run the selected build target
make run                           # Run VM with default settings
make run-host                      # Run VM with host CPU (recommended)
make run-test                      # Run VM with temporary disk
make stop                          # Stop running VM
make clean                         # Remove built artifacts
make clean-disk                    # Remove disk images
make format                        # Format Nix files
make show                          # Show flake outputs
make update                        # Update flake inputs
make shell                         # Enter development shell

Useful variables:

TARGET_SYSTEM=x86_64-linux
TARGET_PACKAGE=automata-iso
CONTAINER_RUNTIME=docker
CONTAINER_PLATFORM=linux/amd64
BUILD_CONTAINER_FILE=Containerfile.build
BUILD_IMAGE_TAG=automataos-build:x86_64-linux-automata-iso-v0.1.0

Running the VM

After a native nix build, or after producing a compatible local result symlink, run the VM with:

nix run .#run-vm
nix run .#run-vm-host
./result/bin/run-nixos-vm

The helper script still works for a host-local result:

./scripts/run-vm.sh
./scripts/run-vm.sh -cpu host -smp 4
./scripts/run-vm.sh -nographic

Use the exported disk images directly:

make run-qemu TARGET_SYSTEM=aarch64-linux
make run-qemu TARGET_SYSTEM=x86_64-linux
make run-qemu-iso TARGET_SYSTEM=x86_64-linux
make run-qemu-disk TARGET_SYSTEM=aarch64-linux
make run-qemu-disk TARGET_SYSTEM=x86_64-linux QEMU_IMAGE=/absolute/path/to/custom-image.qcow2
make test-qemu TARGET_SYSTEM=aarch64-linux
make test-qemu TARGET_SYSTEM=x86_64-linux
make test-qemu TARGET_SYSTEM=x86_64-linux QEMU_IMAGE=/absolute/path/to/custom-image.qcow2

The host-QEMU targets auto-select a proven bootable artifact per architecture:

aarch64-linux defaults to the exported automata-raw-efi image and uses the host qemu-system-aarch64 binary with EFI firmware.
x86_64-linux defaults to the exported automata-iso image and uses the host qemu-system-x86_64 binary.
Disk boots default to -snapshot so downloaded artifacts stay unchanged while you test them.
Set QEMU_IMAGE=/absolute/path/to/image.qcow2 to boot a specific local qcow2 file instead of auto-discovering an exported artifact.
Exported .img and .qcow2 files are made owner-writable so UTM and other hypervisors can attach them as writable disks. ISO files remain read-only.

You can still invoke QEMU manually if you prefer:

qemu-system-x86_64 -cdrom dist/x86_64-linux/automata-iso-v0.1.0/*.iso
qemu-system-x86_64 -drive if=pflash,format=raw,readonly=on,file=/opt/homebrew/share/qemu/edk2-x86_64-code.fd -snapshot -drive file=dist/x86_64-linux/automata-qcow-efi-v0.1.0/*.qcow2,if=virtio,format=qcow2
qemu-system-aarch64 -bios /opt/homebrew/share/qemu/edk2-aarch64-code.fd -snapshot -drive file=dist/aarch64-linux/automata-raw-efi-v0.1.0/*.img,if=virtio,format=raw
sudo dd if=dist/x86_64-linux/automata-iso-v0.1.0/*.iso of=/dev/<usb-device> bs=16M status=progress conv=fsync
sudo dd if=dist/aarch64-linux/automata-raw-efi-v0.1.0/*.img of=/dev/<usb-device> bs=16M status=progress conv=fsync

Deployment Flow

System boots and starts k3s.
automata-deploy waits for the cluster to be ready.
The deployment creates namespaces and installs supporting services.
The Automata Helm chart is deployed from /etc/automata/source/deploy/k8s.
automata-import imports /var/lib/automata/automata-local.tar when present.

Accessing Automata

After the VM boots and the deployment completes:

https://automata.<vm-ip>.nip.io/

Find the VM IP from inside the VM:

hostname -I

Read the generated admin password:

cat /var/log/automata-deploy.log

Configuration

Edit modules/automata.nix to customize the k3s and Automata deployment.

Load a custom Automata image into the VM:

scp automata-local.tar root@<vm-ip>:/var/lib/automata/
k3s ctr images import /var/lib/automata/automata-local.tar

Nix Flake Commands

nix flake show
nix flake update
nix develop
nix fmt
nix build .#packages.x86_64-linux.automata-image
nix build .#packages.aarch64-linux.automata-image
nix build .#packages.x86_64-linux.automata-iso
nix build .#packages.x86_64-linux.automata-qcow-efi
nix build .#packages.aarch64-linux.automata-raw-efi

Troubleshooting

Native Build Fails on a Non-Linux Host

Use the containerized builder:

make build-docker TARGET_SYSTEM=aarch64-linux
make build-podman TARGET_SYSTEM=x86_64-linux

VM Won't Boot

ls -la vm-disk/nixos.qcow2
rm -rf vm-disk
./scripts/run-vm.sh

k3s Won't Start

systemctl status k3s
journalctl -u k3s -f

Deployment Fails

journalctl -u automata-deploy -f
kubectl apply -f /etc/automata/source/deploy/k8s

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github		.github
modules		modules
scripts		scripts
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODEOWNERS		CODEOWNERS
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Containerfile.build		Containerfile.build
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
VERSION		VERSION
flake.lock		flake.lock
flake.nix		flake.nix
shell.nix		shell.nix

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

AutomataOS

Overview

Build Support

Project Structure

Quick Start

Prerequisites

Native Builds

Containerized Builds

Makefile Commands

Running the VM

Deployment Flow

Accessing Automata

Configuration

Nix Flake Commands

Troubleshooting

Native Build Fails on a Non-Linux Host

VM Won't Boot

k3s Won't Start

Deployment Fails

Links

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

AutomataOS

Overview

Build Support

Project Structure

Quick Start

Prerequisites

Native Builds

Containerized Builds

Makefile Commands

Running the VM

Deployment Flow

Accessing Automata

Configuration

Nix Flake Commands

Troubleshooting

Native Build Fails on a Non-Linux Host

VM Won't Boot

k3s Won't Start

Deployment Fails

Links

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages