@crvouga/dev-fleet 0.3.0 → 0.5.0

package/docs/support-matrix.md

@@ -0,0 +1,36 @@
+# Support matrix
+
+Which platforms dev-fleet runs on, in which role, and what happens to the
+rest. The default is one macOS manager and Ubuntu workers treated as cattle.
+
+- **supported**: converged, measured and tested on every pull request.
+- **best effort**: works and is not tested as a fleet role.
+- **refused**: stopped with the named reason before anything is installed.
+
+<!-- Generated by `bun src/machine/support-matrix.ts` from ansible/macos/policy.json, ansible/ubuntu/policy.json and ansible/platforms.json; features/rules/support-matrix.feature fails when it differs. -->
+
+| Role           | Platform  | Versions            | Architectures   | Status      | Note                                                                                      |
+| -------------- | --------- | ------------------- | --------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| manager        | macOS     | 14 or newer         | arm64, x86_64   | supported   | ansible/macos/policy.json                                                                 |
+| worker         | Ubuntu    | 26.04 (resolute)    | amd64, arm64    | supported   | ansible/ubuntu/policy.json; a machine of its own, physical or virtual                     |
+| manager        | any other | any                 | any             | refused     | The fleet configuration accepts only a macOS manager.                                     |
+| worker         | Ubuntu    | any other release   | any             | refused     | UBUNTU_BASELINE_MISMATCH                                                                  |
+| worker         | Ubuntu    | an accepted release | any other       | refused     | UBUNTU_BASELINE_MISMATCH                                                                  |
+| worker         | Debian    | any                 | any             | refused     | UBUNTU_BASELINE_MISMATCH                                                                  |
+| worker         | macOS     | any                 | any             | refused     | The fleet configuration accepts only Linux workers.                                       |
+| worker         | Windows   | any                 | any             | refused     | The fleet configuration accepts only Linux workers.                                       |
+| worker         | WSL2      | any                 | any             | refused     | WORKER_ENVIRONMENT_UNSUPPORTED                                                            |
+| worker         | container | any                 | any             | refused     | WORKER_ENVIRONMENT_UNSUPPORTED                                                            |
+| toolchain only | macOS     | any                 | arm64, x86_64   | best effort | No fleet role: devfleet bootstrap installs the pinned tools (docs/machine-setup.md).      |
+| toolchain only | Linux     | any                 | x86_64, aarch64 | best effort | No fleet role: devfleet bootstrap installs the pinned tools (docs/machine-setup.md).      |
+| toolchain only | WSL2      | any                 | x86_64          | best effort | Treated as Linux: devfleet bootstrap installs the pinned tools (docs/machine-setup.md).   |
+| toolchain only | Windows   | any                 | x64             | best effort | No fleet role: bootstrap/bootstrap.ps1 installs the pinned tools (docs/machine-setup.md). |
+| toolchain only | Alpine    | any                 | any             | refused     | musl: the pinned mise build needs glibc.                                                  |
+
+A worker is refused by the first check that can tell: the fleet configuration
+refuses a worker that is not Linux, the platform probe refuses another
+release, CPU or environment (`ubuntu:release`, `platform:environment`), and
+the bootstrap and the Ubuntu baseline refuse them again on the machine.
+
+Supporting another platform means adding it to the policy that names it, with
+its package pins, a fresh-box job and its row here.

package/docs/ubuntu-sync.md

@@ -61,10 +61,9 @@ resolve enrolled fleet
 
 Bare invocation selects every canonical Linux and macOS node. It does not mean
 “this computer,” and the manager is not implicitly a deployment target. Its own
-node is targeted only if explicitly declared in Fleet membership. Ubuntu 26.04 is
-the accepted worker platform; a node declared `"os": "macOS"` runs the same phases
-best effort through `ansible/macos` (see the platform matrix below).
-Windows machines stay declared for diagnostics and are never converged.
+node is targeted only if explicitly declared in Fleet membership. Workers are the
+Ubuntu releases the [support matrix](support-matrix.md) lists; it also says what
+is refused (macOS and Windows workers, WSL2, containers) and why.
 `--node ID` filters troubleshooting/rollout. `--all` is an explicit spelling of the
 default. Neither flag authorizes managing arbitrary Tailscale peers.
 
@@ -117,9 +116,8 @@ included, to the exact version in `ansible/ubuntu/policy.json`. The interactive
   roster in the [fleet state](state.md), using the existing roster schema.
   Preserve workspace/runtime paths, capabilities and explicit `tailscaleId`
   bindings.
-- Workstation network consumers derive their inventory from Fleet. The old file
-  is retained only as `packages/fleet/migrations/workstation-network-v1.json` for
-  lossless identity-path migration; conflicts fail rather than silently winning.
+- Workstation network consumers derive their inventory from the fleet
+  configuration; conflicts fail rather than silently winning.
 - Manager approval: the `enrollment` document in the [fleet state](state.md).
   Manager deployment lock: `~/.local/share/personal/fleet/manager/sync.lock`.
 - Remote source: `~/.local/share/personal/fleet/revisions/FULL_SHA`.
@@ -211,14 +209,19 @@ vault kv get -field=FLEET_WORKER_TOKEN_WORKER_ONE secret/personal/prd \
   | ssh worker-one 'vault login -address=https://vault.example.com -no-print -'
 ```
 
-From then on the node's `personal-worker-auth` timer renews that token and its
-GitHub login, and renders provider configuration from Vault through Workstation.
+From then on the node's `personal-worker-auth` timer renews that token and
+restores its GitHub login from it (`bootstrap/worker-auth.ts`). It renders no
+provider configuration: agent profiles are applied by `fleet-sync`. See
+[Authentication and accounts](authentication.md).
 
 ## Ubuntu and remote-work safety
 
-The declared common baseline is Ubuntu **26.04 LTS**, amd64/arm64. Other releases
-receive `UBUNTU_BASELINE_MISMATCH`; there is no automatic release upgrade or
-package downgrade. Fleet audits release, packages, service state and dpkg
+The accepted releases are named once, in `ansible/ubuntu/policy.json`, and
+listed in the [support matrix](support-matrix.md). Other releases receive
+`UBUNTU_BASELINE_MISMATCH`, and WSL2 and containers
+`WORKER_ENVIRONMENT_UNSUPPORTED`; there is no automatic release upgrade or
+package downgrade. Package pins are minimums: see the
+[worker contract](worker-contract.md#package-pins-and-security-updates). Fleet audits release, packages, service state and dpkg
 consistency, declares snapshot sources for managed transactions, and pins its
 selected APT packages. Unrelated applications and package sources are preserved.
 
@@ -268,7 +271,7 @@ promise. Inspect disk/inodes, swap/memory pressure, `systemctl --failed`, and pr
 boot journal evidence locally; sanitize it before sharing. Do not enable automatic
 reboot-on-pressure or kill active work to obtain a green report.
 
-T3 0.1.7's supported administrator policy at `/etc/t3code/policy.json`
+The pinned T3's (`t3_version` in `mise.toml`) supported administrator policy at `/etc/t3code/policy.json`
 disables independent updates and declares the existing managed Codex instance
 plus an OpenCode instance for all five gateway models. Fleet reuses the
 existing `agents/t3.json` renderer; it does not edit the live settings database.

package/docs/worker-contract.md

@@ -12,7 +12,8 @@ devfleet fleet-status --workers
 ```
 
 The manager needs Node/npm, Git, SSH, Tailscale, and its own authorized T3 link.
-Initially each Ubuntu 26.04 worker (or best-effort macOS 14+ node) needs a
+Initially each worker (an Ubuntu release the [support matrix](support-matrix.md)
+lists) needs a
 designated non-root account, trusted SSH access and administrator authorization. Standard Ubuntu cloud-image users
 already commonly have noninteractive sudo; otherwise establish the repository's
 `authorize-sudo.sh` policy once during administrator enrollment. Routine commands
@@ -39,6 +40,32 @@ HEAD. Private rosters contain connection paths and identities, not weaker policy
 | No routine password prompts        | Verified BatchMode SSH, `sudo -n`, source-owned NOPASSWD policy; missing initial authorization is a failure                                                                                                |
 | Keep service authorization alive   | Native service credentials stay per-node; Vault self-renewal timer and GitHub recovery from authorized Vault credentials; expiring T3 links are reported before expiry                                     |
 
+## Package pins and security updates
+
+A pin in `ansible/ubuntu/policy.json` is a **minimum**, never a hold. Ubuntu
+keeps installing security updates by itself, and a worker is not turned red by
+one:
+
+- The Ubuntu baseline installs a pinned package from the snapshot only when it
+  is absent or older than its pin, and never downgrades
+  (`ansible/ubuntu/tasks/install.yml`; every pinned package, `systemd-oomd`
+  included, goes through it).
+- What Ubuntu installs unattended is declared in
+  `/etc/apt/apt.conf.d/52personal-fleet-unattended-upgrades`: security updates
+  only, no automatic reboot, no removals.
+- `worker:package:NAME` passes at the pin, **warns** with
+  `PACKAGE_NEWER_THAN_PIN` above it, and fails with `PACKAGE_BELOW_PIN` below
+  it or when the package is missing. A warning does not block convergence or
+  readiness; it says the pin can be raised when the snapshot moves.
+- Tailscale follows the same rule: a newer Tailscale is kept; an older one
+  stops with `TAILSCALE_UPGRADE_PENDING`, because upgrading an active VPN can
+  drop SSH.
+
+A package run cut off by a power loss is finished by the next sync: the
+baseline waits for the APT lock, runs `dpkg --configure -a` once (bounded to
+ten minutes) and audits again; only a database still inconsistent stops with
+`APT_STATE_BROKEN`.
+
 Health does not mutate configuration, renew tokens, log in, install software, or
 make billable inference requests. It audits the immutable desired worker deployment,
 not an unrelated developer branch. Every declared worker must be enrolled and

package/examples/fleet.json

@@ -29,6 +29,14 @@
       "proxy-tunnel-token": {
         "path": "cliproxy-fleet/tunnel",
         "field": "TUNNEL_TOKEN"
+      },
+      "monitoring-backup-access-key": {
+        "path": "beszel/backups",
+        "field": "ACCESS_KEY_ID"
+      },
+      "monitoring-backup-secret-key": {
+        "path": "beszel/backups",
+        "field": "SECRET_ACCESS_KEY"
       }
     }
   },
@@ -73,7 +81,16 @@
       "hubPort": 8443,
       "publicUrl": "https://beszel.example.com",
       "managerAccount": "fleet-manager@example.com",
-      "viewerAccount": "public-viewer@example.com"
+      "viewerAccount": "public-viewer@example.com",
+      "backups": {
+        "schedule": "0 3 * * *",
+        "keep": 7,
+        "storage": {
+          "bucket": "my-fleet-hub-backups",
+          "endpoint": "https://s3.example.com",
+          "region": "auto"
+        }
+      }
     }
   },
   "ubuntu": {
@@ -92,6 +109,7 @@
     "githubLogin": "example-user",
     "vaultUser": "example-user",
     "toolchain": "mise.lock",
+    "toolProfiles": ["go"],
     "agentProfile": "proxy",
     "unattendedSudo": true,
     "persistentT3": true,

package/llms.txt

@@ -31,6 +31,8 @@ Rules for an agent working in a project that uses dev-fleet:
 - [Ubuntu fleet-sync reference](https://github.com/crvouga/dev-fleet/blob/main/docs/ubuntu-sync.md): enrollment, approval, machine policy by platform, remote-work safety
 - [Worker contract](https://github.com/crvouga/dev-fleet/blob/main/docs/worker-contract.md): what a worker guarantees and how readiness is scoped
 - [Operations](https://github.com/crvouga/dev-fleet/blob/main/docs/operations.md): roster, diagnostics and repairs
+- [Runbooks](https://github.com/crvouga/dev-fleet/blob/main/docs/runbooks.md): every failure code, how to confirm it, the fix and when to escalate
+- [Authentication and accounts](https://github.com/crvouga/dev-fleet/blob/main/docs/authentication.md): where each credential lives, how it reaches each node and how it rotates
 - [Coding agents on every node](https://github.com/crvouga/dev-fleet/blob/main/agents/setup.md): agent launchers and the T3 providers
 - [Releasing](https://github.com/crvouga/dev-fleet/blob/main/docs/releasing.md): how a version is published from one commit (for dev-fleet developers)
 - [Features](https://github.com/crvouga/dev-fleet/blob/main/features/README.md): the behaviour specified in Gherkin (for dev-fleet developers)

package/mise.toml

@@ -110,3 +110,10 @@ docker_desktop_amd64_sha256 = "96b53f9a4a807b6be6207d18f360b9778ff481e1d94b5027b
 
 # Minimal remote development baseline; versions are resolved exclusively by tools + mise.lock.
 worker_tools = "bun,node,gh,python,uv,docker-cli,vault,jq,codex,claude,aqua:anomalyco/opencode,gemini,copilot,http:grok,http:antigravity"
+# Tool profiles a fleet adds to its workers (`worker.toolProfiles` in
+# fleet.json, fleet-wide or per worker): one `worker_profile_<name>` each,
+# naming tools pinned above. bootstrap/worker-tools.ts lists the names.
+worker_profile_web = "pnpm,deno,npm:@yarnpkg/cli-dist"
+worker_profile_go = "go"
+worker_profile_rust = "rust,cmake,ninja"
+worker_profile_jvm = "java"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/dev-fleet",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Keeps a set of development machines in sync: one manager and many workers",
   "license": "MIT",
   "repository": "github:crvouga/dev-fleet",
@@ -72,5 +72,5 @@
   "engines": {
     "node": ">=22"
   },
-  "gitHead": "0c583e40a0c32c0db355e9c0bca6903894945310"
+  "gitHead": "620b8de05d662b4dc9072457580ca4b4eab54242"
 }