What is the Arroyo System?

The Arroyo Concept Operating System is a method of organizing a cluster NixOS within org-mode documents. You read, write, and create human legible documentation with code and configuration embedded within it, and the system extracts that code (colloquially: "tangles" it) in a a Nix Flake which can deploy and manage a cluster of computers.

Adding new functionality to your system is as simple as downloading plaintext org-mode documents and running the arroyo tool. If you don't know how to use the software, the document itself serves as an introduction to the use and abuse of the software under consideration.

• Rebuild of The Complete Computer

• Rebuild of The Complete Computer 0x01: You Can (Not) Compute

• Rebuild of the complete computer 0x02: This is (Not) Advanced (This document, currently version 0x2.22)

This document is the README for the arroyo-system personal system definition repository, it's available on the web as part of my Complete Computing Environment.

NEXT record a video going through this README to produce a new arroyo system cluster

Prerequisites

• Linux host or VM to run this bootstrap environment.

• Nix with flakes (experimental-features nix-command flakes= in ~/.config/nix/nix.conf)

• Emacs with org-mode or another system with org-mode editing capabilities or syntax highlighting. cce-emacs can give you an opinionated one of these.

• arcology tangle tool (see arcology2go)

Set up you ~/org

You'll use ~/org to organize your life, and it will in turn organize your computer in ~/nix.

Start by cloning this arroyo system repository in to ~/org/arroyo-system. This contains this bootstrap document and template files which will tangle to ~/nix. You'll edit these files to add new systems to your cluster.

git clone http://code.rix.si/rrix/arroyo-system ~/org/arroyo-system
git -C ~/org/arroyo-system checkout -b $USER

cce-core contains a base NixOS distribution, a set of decent defaults that work will with this system.

git clone https://code.rix.si/rrix/cce-core ~/org/cce-core

cce-workstation defines a KDE desktop suitable for your NixOS Endpoint.

git clone https://code.rix.si/rrix/cce-workstation ~/org/cce-workstation

cce-emacs and cce-emamcs-org gives you an Emacs suitable for working within the Arroyo Concept Operating System.

git clone https://code.rix.si/rrix/cce-emacs ~/org/cce-emacs
git clone https://code.rix.si/rrix/cce-emacs-org ~/org/cce-emacs-org

cce-wobserver sets up a private cluster of sovereign web services. It serves as the "hub" of the Concept Operating System.

git clone https://code.rix.si/rrix/cce-wobserver ~/org/cce-wobserver

arcology2go is the application which provides the tangle tool, an Android org-mode journaling app, and an org-mode web publishing platform. If you don't want to set up the Wobserver you can probably just nix run this or provide it as as a remote ARROYO_INPUT but you'll want it on hand.

git clone https://code.rix.si/rrix/arcology2go ~/org/arcology2go

Tangling and flooding

You can start by running

nix run git+http://code.rix.si/rrix/arcology2go?submodules=1 -- flood --db ~/org/arcology.db

This populates a SQLite3 database with metadata extracted from these org-mode files, then uses that metadata to generate the Arroyo System Flake. File keywords and heading properties like :ARROYO_SYSTEM_OUTPUT:, #+ARROYO_SYSTEM_ROLE, :ARROYO_NIXOS_MODULE: used by the Flake generator to define Flake inputs and outputs. The tangle tool executes Lua embedded in the documents to answer requests like "give me a list of all the NixOS modules for the endpoint role" and embed that in the nixosConfiguration output definition for your laptop.

• If you chose to include arcology2go in your ~/org, you should now have an arcology command in your PATH, otherwise you can keep =nix run='ing it.

• flood re-tangles everything and reindexes the DB

• arcology tangle ./<file>.org --db ~/org/arcology.db for iterative single-file work

• structural changes to ARROYO_INPUT ARROYO_OUTPUT ARROYO_NIXOS_MODULE keywords require a flood (tangle retangles source blocks but reads keywords from the stale DB)

Defining your first host

• Copy the myhost heading in systems.org

• Set networking.hostName and system.stateVersion to "26.05" then update the doc to refer to the new hostname :%s/myhost/THE_HOSTNAME/gc

• Write a hardware-configuration.nix (use nixos-generate-config on the target machine) and place the contents of it in the host definition.

• populate the :ARROYO_AGE_RECIPIENT: property in the drawer

• The :ARROYO_OUTPUT: keyword declares the host output snippet

• The :ARROYO_SYSTEM_ROLE: property filters which modules the <<host-modules("endpoint")>> Lua generator pulls in

• add tailscale_THE_HOSTNAME secret to secrets/endpoint.yaml

Building and switching

arcology2 flood -d ~/org/ --all-modules
nixos-rebuild switch --flake ~/nix#myhost

After any org edit: arcology tangle (or flood for structural changes) → nixos-rebuild switch.

Adding your own modules

Use #+ARROYO_NIXOS_MODULE: #+ARROYO_HOME_MODULE: :ARROYO_SYSTEM_ROLE: keywords in org headings to register modules. Example:

,** My Module
:PROPERTIES:
:ID:       my-module
:ARROYO_NIXOS_MODULE: nixos/my-module.nix
:ARROYO_SYSTEM_ROLE: endpoint
:END:

,#+begin_src nix :tangle ~/nix/nixos/my-module.nix
{ ... }: { services.some-thing.enable = true; }
,#+end_src

The cce-* repos are the canonical corpus of example modules.

Adding flake inputs

Use #+ARROYO_INPUT: to declare flake input snippets. Example (home-manager-input.nix):

,#+begin_src nix :tangle ~/nix/snippets/home-manager-input.nix :mkdirp yes
home-manager = {
  url = "github:nix-community/home-manager/release-26.05";
  inputs.nixpkgs.follows = "nixpkgs";
};
,#+end_src

The system roles

• endpoint — laptops and desktops (full desktop, home-manager, Emacs)

• server — the Wobserver (community homeserver)

• settop — HTPC / media center

• edge — edge server VM (proxy in front of the Wobserver)

• droid - t184256/nix-on-droid environment

Pick one per host via :ARROYO_SYSTEM_ROLE:.

Verification

nix --extra-experimental-features "nix-command flakes" flake check ~/nix --no-build

This is the only "test" the project has.

Where to go next

The cce-* repos cloned above are the example of a complete Arroyo System. The creator's Website is a good place to go. Go deploy your own cluster. Deploy a Wobserver and invite your friends.

Troubleshooting

• arcology tangle doesn't reindex the DB, only flood (or index) updates keyword rows.

• property drawers only allow one of each keyword, multiples in one drawer silently overwrite. The parser will split ARROYO_* keywords on spaces (:ARROYO_SYSTEM_ROLE: endpoint server)