@crvouga/dev-fleet 0.8.0 → 0.9.1

package/examples/workers-from-infrastructure/main.tf

@@ -0,0 +1,132 @@
+# Workers from infrastructure as code: an example, with a local virtual
+# machine (libvirt) standing in for the provider. Any tool or provider that
+# can boot a stock Ubuntu image with cloud-init user data and write a file
+# works the same way; dev-fleet never calls a provider and never creates a
+# machine. It reads the worker records this writes (worker-records.json, see
+# schema/worker-record.schema.json) because fleet.json names the file:
+#
+#   "workerRecords": [{ "file": "infra/worker-records.json" }]
+#
+# The handoff, from the fleet project (OpenTofu installed, libvirt on this
+# machine):
+#
+#   1. Declare the worker. With only `tailnet_name` and `user` set, this
+#      writes its record and creates nothing else:
+#        tofu -chdir=infra apply -var-file=workers.tfvars
+#   2. Seed it. dev-fleet generates its host key, pins it in the fleet state
+#      and writes the cloud-init user data:
+#        npx devfleet fleet-node-seed --id rented-one \
+#          --output infra/seed/rented-one.yaml --apply --yes --json
+#      Put the path in `seed` (and, if you like, the printed hostKey in
+#      `host_key`, so that the record carries it too).
+#   3. Create the machine, then converge it:
+#        tofu -chdir=infra apply -var-file=workers.tfvars
+#        npx devfleet fleet-sync --non-interactive
+#   4. Remove it: drop it from `workers` and apply, or `tofu destroy`. Its
+#      record is gone, so the next `npx devfleet fleet-sync` retires it: its
+#      token, pinned host key, monitoring system and T3 link are removed.
+#
+# What the machine must offer (image, architecture, size, access, network) is
+# docs/worker-requirements.md. For a hosted provider only these change: the
+# provider block and its credentials, the image (its stock Ubuntu image of an
+# accepted release, in place of `ubuntu_image`), the instance type (at least
+# the minimum size, in place of `memory_mib` and `vcpus`) and the network (a
+# private network, or inbound rules with nothing open, in place of
+# `network_interface`). The seed goes in as the instance's user data and the
+# records come out the same way.
+#
+# This example cannot be applied in dev-fleet's CI (it needs a libvirt host
+# and a tailnet), so it is not proven there; the record format and what
+# fleet-sync does with records are (features/cli/fleet-validate.feature,
+# features/fleet-sync/node-lifecycle.feature). Pin the provider in your own
+# project: `tofu init` writes .terraform.lock.hcl.
+
+terraform {
+  required_providers {
+    libvirt = { source = "dmacvicar/libvirt" }
+    local   = { source = "hashicorp/local" }
+  }
+}
+
+provider "libvirt" {
+  uri = "qemu:///system"
+}
+
+variable "ubuntu_image" {
+  description = "A stock Ubuntu cloud image (a URL or a local path) of the release fleet.json names."
+  type        = string
+}
+
+variable "workers" {
+  description = "The workers, by fleet ID. A worker with a seed is created; one without is only declared."
+  type = map(object({
+    tailnet_name = string
+    user         = string
+    seed         = optional(string)
+    host_key     = optional(string)
+    memory_mib   = optional(number, 8192)
+    vcpus        = optional(number, 4)
+    hourly_rate  = optional(number)
+  }))
+}
+
+locals {
+  seeded = { for id, worker in var.workers : id => worker if worker.seed != null }
+}
+
+resource "libvirt_volume" "image" {
+  name   = "devfleet-ubuntu.qcow2"
+  source = var.ubuntu_image
+}
+
+resource "libvirt_volume" "disk" {
+  for_each       = local.seeded
+  name           = "${each.key}.qcow2"
+  base_volume_id = libvirt_volume.image.id
+  size           = 64 * 1024 * 1024 * 1024
+}
+
+resource "libvirt_cloudinit_disk" "seed" {
+  for_each  = local.seeded
+  name      = "${each.key}-seed.iso"
+  user_data = file(each.value.seed)
+}
+
+resource "libvirt_domain" "worker" {
+  for_each  = local.seeded
+  name      = each.key
+  memory    = each.value.memory_mib
+  vcpu      = each.value.vcpus
+  cloudinit = libvirt_cloudinit_disk.seed[each.key].id
+
+  disk {
+    volume_id = libvirt_volume.disk[each.key].id
+  }
+
+  network_interface {
+    network_name = "default"
+  }
+}
+
+# The handoff: one record per declared worker. Only what dev-fleet needs to
+# reach the machine, and nothing that names this tool or the provider.
+resource "local_file" "worker_records" {
+  filename        = "${path.module}/worker-records.json"
+  file_permission = "0644"
+  content = jsonencode({
+    version = 1
+    workers = [
+      for id, worker in var.workers : merge(
+        { id = id, tailnetName = worker.tailnet_name, user = worker.user },
+        worker.host_key == null ? {} : { hostKey = worker.host_key },
+        worker.hourly_rate == null ? {} : { billing = { hourlyRate = worker.hourly_rate } },
+        { labels = { source = "local-vm" } },
+      )
+    ]
+  })
+}
+
+output "fleet_workers" {
+  description = "The same records, for a fleet.json that runs a command instead: { \"command\": [\"tofu\", \"-chdir=infra\", \"output\", \"-json\", \"fleet_workers\"] }."
+  value       = jsondecode(local_file.worker_records.content)
+}

package/examples/workers-from-infrastructure/worker-records.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "../../schema/worker-record.schema.json",
+  "version": 1,
+  "workers": [
+    {
+      "id": "rented-one",
+      "tailnetName": "rented-one.tail0a1b2c.ts.net",
+      "user": "dev",
+      "hostKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleHostKeyOfARentedWorker",
+      "billing": { "hourlyRate": 0.5 },
+      "labels": { "source": "local-vm" }
+    }
+  ]
+}

package/llms.txt

@@ -1,6 +1,6 @@
 # dev-fleet
 
-> dev-fleet keeps a set of development machines in sync: one macOS **manager** and any number of Ubuntu 26.04 **workers** reached over SSH and Tailscale. It is used as the npm package `@crvouga/dev-fleet` (CLI `devfleet`) from a project of your own that holds `fleet.json` and pins the package version; one command, `devfleet fleet-sync`, converges every machine to the commit that version was published from. The fleet state lives in an S3-compatible bucket you own.
+> dev-fleet keeps a set of development machines in sync: one macOS **manager** and any number of Ubuntu (26.04 or 24.04) **workers** reached over SSH and Tailscale. It is used as the npm package `@crvouga/dev-fleet` (CLI `devfleet`) from a project of your own that holds `fleet.json` and pins the package version; one command, `devfleet fleet-sync`, converges every machine to the commit that version was published from. The fleet state lives in an S3-compatible bucket you own.
 
 Rules for an agent working in a project that uses dev-fleet:
 
@@ -16,10 +16,12 @@ Rules for an agent working in a project that uses dev-fleet:
 - [README](https://github.com/crvouga/dev-fleet/blob/main/README.md): what dev-fleet assumes, quickstart, versions, adding a machine, known limits
 - [Example fleet.json](https://github.com/crvouga/dev-fleet/blob/main/examples/fleet.json): a complete configuration with placeholders (`npx devfleet fleet-state --example` prints it)
 - [fleet.json schema](https://github.com/crvouga/dev-fleet/blob/main/schema/fleet.schema.json): JSON Schema for the fleet configuration
+- [Check-ID registry](https://github.com/crvouga/dev-fleet/blob/main/schema/check-ids.json): every check ID a report can carry, with what it means, whether it can block readiness (severity) and what repairs it (a fleet-repair recipe, or why only a person can); generated from the code
 
 ## Operate it
 
 - [Fleet state](https://github.com/crvouga/dev-fleet/blob/main/docs/state.md): the bucket, replication, replacing the manager, what the bucket does not hold yet
+- [Worker requirements](https://github.com/crvouga/dev-fleet/blob/main/docs/worker-requirements.md): what a machine must offer to be a worker (image, architecture, size, access, first-boot data, network), each with its check and failure code, and what changes for a hosted provider
 - [Topology](https://github.com/crvouga/dev-fleet/blob/main/docs/topology.md): the manager and worker roles and the canary
 - [What is declared, and where](https://github.com/crvouga/dev-fleet/blob/main/docs/declared.md): what is pinned on a machine and what is not
 - [Provider accounts](https://github.com/crvouga/dev-fleet/blob/main/docs/accounts.md): the account roster, its states and checks, adding or removing an account, propagation to every node, account selection

package/mise.lock

@@ -1355,6 +1355,35 @@ url = "https://github.com/getsops/sops/releases/download/v3.13.3/sops-v3.13.3.am
 url_api = "https://api.github.com/repos/getsops/sops/releases/assets/486808200"
 provenance = "cosign"
 
+[[tools.tmux]]
+version = "3.8"
+backend = "aqua:tmux/tmux-builds"
+specifiers = ["3.8"]
+
+[tools.tmux."platforms.linux-arm64"]
+checksum = "sha256:f399311b1159705e69839eaf4f6f68c8b8540dc3a8538b87c30dedb9c3c7fc23"
+checksum_source = "mise-versions"
+url = "https://github.com/tmux/tmux-builds/releases/download/v3.8/tmux-3.8-linux-arm64.tar.gz"
+url_api = "https://api.github.com/repos/tmux/tmux-builds/releases/assets/721688993"
+
+[tools.tmux."platforms.linux-x64"]
+checksum = "sha256:147849ff18b62a8aa3d5d8f75dd07c3f9fdfad529f932236afdec838fc1d15e1"
+checksum_source = "mise-versions"
+url = "https://github.com/tmux/tmux-builds/releases/download/v3.8/tmux-3.8-linux-x86_64.tar.gz"
+url_api = "https://api.github.com/repos/tmux/tmux-builds/releases/assets/721688991"
+
+[tools.tmux."platforms.macos-arm64"]
+checksum = "sha256:ec926bbf28ddf55d0dc7c9791d43e03e251ddab392d763f7fbb38d4b8408d051"
+checksum_source = "mise-versions"
+url = "https://github.com/tmux/tmux-builds/releases/download/v3.8/tmux-3.8-macos-arm64.tar.gz"
+url_api = "https://api.github.com/repos/tmux/tmux-builds/releases/assets/721688988"
+
+[tools.tmux."platforms.macos-x64"]
+checksum = "sha256:e7b92e51d9e9610ce80d1c477da1e6ff6a6398ea6b6b4d4ff7b19cf60f594555"
+checksum_source = "mise-versions"
+url = "https://github.com/tmux/tmux-builds/releases/download/v3.8/tmux-3.8-macos-x86_64.tar.gz"
+url_api = "https://api.github.com/repos/tmux/tmux-builds/releases/assets/721688994"
+
 [[tools.usql]]
 version = "0.21.6"
 backend = "aqua:xo/usql"

package/mise.toml

@@ -1,7 +1,7 @@
 # Shared workstation toolchain. Bootstrap installs this globally; projects may override it.
 # Commit mise.lock whenever changing these pins.
-# min_version is also the exact mise bootstrap/bootstrap.sh installs; bump the
-# mise_*_sha256 digests under [vars] with it.
+# min_version is also the exact mise bootstrap/bootstrap.sh installs; the
+# mise_*_sha256 digests under [vars] move with it (bun bootstrap/pins.ts mise).
 min_version = "2026.10.24"
 
 [settings]
@@ -30,6 +30,8 @@ go = "1.27.3"
 jq = "1.8.2"
 yq = "4.54.1"
 ripgrep = "15.2.0"
+# Terminal multiplexer for long agent and build sessions on a worker.
+tmux = { version = "3.8", os = ["linux", "macos"] }
 fd = "10.5.0"
 fzf = "0.74.5"
 bat = "0.26.1"
@@ -109,7 +111,7 @@ docker_desktop_arm64_sha256 = "9c6f13ce4edda2abf20d801552b6acb96acd3d64b3e91b50c
 docker_desktop_amd64_sha256 = "96b53f9a4a807b6be6207d18f360b9778ff481e1d94b5027bdf1ae2a22d837cb"
 
 # 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"
+worker_tools = "bun,node,gh,python,uv,docker-cli,vault,jq,tmux,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/dev-fleet",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "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": "3f13ebe4bda2cf813a68ee45678627b2e21660d5"
+  "gitHead": "3a465d53335387bf4851216ad8df67d1866fe887"
 }