# FormalSpec

> Declare your machines in Starlark and keep them identical, on any Linux distro and on macOS.

Every page below is markdown. All of them in one file: https://os.formalsnake.dev/docs/llms-full.txt.

## Start

- [FormalSpec](https://os.formalsnake.dev/docs/index.md): Declare your machines in Starlark and keep them identical, on any Linux distro and on macOS.
- [Install fspec](https://os.formalsnake.dev/docs/install.md): Build the fspec binary from source with cargo or Nix, and check that it runs.
- [Your first spec](https://os.formalsnake.dev/docs/first-spec.md): Declare the machine you are on, pin its packages, apply it, change it and roll it back.

## Concepts

- [How FormalSpec works](https://os.formalsnake.dev/docs/concepts/how-it-works.md): The spec, the lock, state, scopes, generations and the store, and what plan and apply do with them.
- [Hosts and modules](https://os.formalsnake.dev/docs/concepts/hosts-and-modules.md): Declare several machines in one spec, share configuration between them with modules, and split the spec into files.

## Configure a host

- [Packages](https://os.formalsnake.dev/docs/guides/packages.md): Pick a source for each package, pin it with fspec update, and control what gets linked onto PATH.
- [Files](https://os.formalsnake.dev/docs/guides/files.md): Write, link, seed or merge config files, generate them from Starlark data, and handle drift.
- [Secrets](https://os.formalsnake.dev/docs/guides/secrets.md): Keep age-encrypted secrets in the spec repository and decrypt them onto each host at apply and at boot.
- [Services and timers](https://os.formalsnake.dev/docs/guides/services.md): Declare long-running services and scheduled jobs once, and run them on systemd, launchd, runit, OpenRC, dinit or s6.
- [Users and macOS settings](https://os.formalsnake.dev/docs/guides/users-and-macos.md): Manage accounts, login shells and groups, and set macOS defaults, power, firewall, apps and fonts.
- [Project environments](https://os.formalsnake.dev/docs/guides/dev-environments.md): Give a repository its own locked tools, system libraries, environment and services with a dev.star.

## Operate

- [Removal and rollback](https://os.formalsnake.dev/docs/guides/removal-and-rollback.md): What happens when you delete a line from the spec, where app data goes, how to roll back a generation, and how to clean up old ones.
- [Remote hosts](https://os.formalsnake.dev/docs/guides/remote-hosts.md): Keep several machines in one spec repository and apply or plan them over ssh from one place.
- [Sync between hosts](https://os.formalsnake.dev/docs/guides/sync.md): Move app data a spec cannot declare, such as signed-in accounts, keyring secrets and picture folders, between your own machines with fspec sync.
- [Building from source](https://os.formalsnake.dev/docs/guides/source-builds.md): Build git(...) packages at a locked commit, patch packages, and serve the builds from CI or a builder machine.

## The operating system

- [The system layer](https://os.formalsnake.dev/docs/guides/system-layer.md): Declare a host's kernel, bootloader and base packages as a bootc image or as a classic distro's packages, and how each one pins and rolls back.
- [Switching distros](https://os.formalsnake.dev/docs/guides/switching-distros.md): Move a host to another distro, or another bootc image, while your home and FormalSpec's store carry over, and get a disk onto a layout that holds several roots.
- [The installer](https://os.formalsnake.dev/docs/guides/installer.md): Boot the FormalSpec installer ISO, install a new machine from a distro and a preset or from an existing spec, and what you find on disk afterwards.

## Reference

- [Commands](https://os.formalsnake.dev/docs/reference/commands.md): Every fspec command and flag, grouped by what you use it for.
- [Builtins](https://os.formalsnake.dev/docs/reference/builtins.md): Every function a spec.star, dev.star or secrets.star can call, with its arguments and defaults.
- [The lock file](https://os.formalsnake.dev/docs/reference/lock-file.md): What fspec.lock holds, how fspec update writes it, and how to read a change in review.
- [Files and paths](https://os.formalsnake.dev/docs/reference/paths.md): Every directory fspec reads or writes on a host, what lives there and which scope owns it.

## Help

- [Coming from Nix](https://os.formalsnake.dev/docs/from-nix.md): How NixOS, nix-darwin and Home Manager constructs map to FormalSpec, with side-by-side examples and what you give up.
- [Troubleshooting](https://os.formalsnake.dev/docs/troubleshooting.md): Errors fspec prints, what causes each one and how to fix it, organised by symptom.