Agentic Coding Flywheel Setup (ACFS)

🌐 agent-flywheel.com — Interactive setup wizard for beginners

From zero to fully-configured agentic coding VPS in 30 minutes. A complete bootstrapping system that transforms a fresh Ubuntu or Arch-based machine into a professional AI-powered development environment.

Quick Install

{ acfs_installer="$(curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh")" || acfs_installer="$(curl -fsSL "https://cdn.jsdelivr.net/gh/Dicklesworthstone/agentic_coding_flywheel_setup@main/install.sh")"; } && printf '%s\n' "$acfs_installer" | bash -s -- --yes --mode vibe

NOTE

raw.githubusercontent.com is listed first deliberately. jsDelivr caches a mutable @main reference, so it can serve an installer that is hours or days behind the repository. When that happens the stale installer's bootstrap extraction list does not match the current checksum ledger and the install fails with INTEGRITY: <file> missing — a failure that looks like a repository defect but is purely a CDN cache artifact. Keeping the authoritative source primary and the CDN as fallback preserves the resilience without that failure mode. Please do not reorder these. Each download is buffered before execution so a failed request cannot concatenate a partial installer with the fallback response.

The installer is idempotent—if interrupted, simply re-run it. Resume revisits installation phases and uses component checks to repair incomplete installations.

Using a cloud agent instead of a VPS? The cloud agent guide has tested Claude Code / Codex setups and researched recipes for other Linux agents. See cloud environments.

Production environments: For stable, reproducible installs, pin to a tagged release or specific commit:

# Preferred: use a tagged release (e.g., v0.9.0)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/v0.9.0/install.sh" | bash -s -- --yes --mode vibe --ref v0.9.0

# Alternative: pin to a specific commit SHA
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/abc1234/install.sh" | bash -s -- --yes --mode vibe --ref abc1234

Tagged releases are tested and stable. Passing --ref ensures all fetched scripts use the same version.

TL;DR

ACFS is a complete system for bootstrapping agentic coding environments:

Why you'd care:

• Zero to Hero: Takes complete beginners from "I have a laptop" to "I have Claude/Codex/Antigravity agents writing code for me on a VPS"
• One-Liner Magic: A single curl | bash command installs 30+ tools, configures everything, and sets up three AI coding agents
• Vibe Mode: Pre-configured for maximum velocity—passwordless sudo, dangerous agent flags enabled, optimized shell environment
• Battle-Tested Stack: Includes the complete Agent Flywheel stack (core tools + utilities) for agent orchestration, coordination, and safety

What you get:

• Modern shell (zsh + oh-my-zsh + powerlevel10k)
• All language runtimes (bun, uv/Python, Rust, Go)
• Agent coordination tools (NTM, MCP Agent Mail, SLB)
• Cloud CLIs (Vault, Wrangler, Supabase, Vercel)
• And 20+ more developer tools

Coding agents: 7 modules — 3 installed by default (Antigravity CLI, Claude Code, Codex CLI); 3 optional (Grok CLI, oh-my-pi, OpenCode); 1 legacy, off by default (Gemini CLI). Full roster in Compatible AI Coding Agents.

The ACFS Experience

graph LR
    %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%

    subgraph user ["User's Machine"]
        LAPTOP["Laptop"]
        BROWSER["Browser"]
    end

    subgraph wizard ["Wizard Website"]
        STEPS["13-Step Guide"]
    end

    subgraph vps ["Fresh VPS"]
        UBUNTU["Ubuntu 22.04 / 24.04 LTS"]
        INSTALLER["install.sh"]
        CONFIGURED["Configured VPS"]
    end

    subgraph agents ["AI Agents"]
        CLAUDE["Claude Code"]
        CODEX["Codex CLI"]
        AGY["Antigravity CLI"]
    end

    LAPTOP --> BROWSER
    BROWSER --> STEPS
    STEPS -->|SSH| UBUNTU
    UBUNTU --> INSTALLER
    INSTALLER --> CONFIGURED
    CONFIGURED --> CLAUDE
    CONFIGURED --> CODEX
    CONFIGURED --> AGY

    classDef user fill:#e3f2fd,stroke:#90caf9,stroke-width:2px
    classDef wizard fill:#fff8e1,stroke:#ffcc80,stroke-width:2px
    classDef vps fill:#f3e5f5,stroke:#ce93d8,stroke-width:2px
    classDef agent fill:#e8f5e9,stroke:#a5d6a7,stroke-width:2px

    class LAPTOP,BROWSER user
    class STEPS wizard
    class UBUNTU,INSTALLER,CONFIGURED vps
    class CLAUDE,CODEX,AGY agent

For Beginners

ACFS includes a step-by-step wizard website at agent-flywheel.com that guides complete beginners through:

1. Installing a terminal on their local machine
2. Generating SSH keys (for secure access later)
3. Renting a VPS from providers like OVH or Contabo
4. Connecting via SSH with a password (initial setup)
5. Running the installer (which sets up key-based access)
6. Reconnecting securely with your SSH key
7. Starting to code with AI agents

For Developers

ACFS is a one-liner that transforms any fresh Ubuntu or Arch-based machine into a fully-configured development environment with modern tooling and three AI coding agents ready to go.

For Teams

ACFS provides a reproducible, idempotent setup that ensures every team member's VPS environment is identical—eliminating "works on my machine" for agentic workflows.

Architecture & Design

ACFS centers its tool inventory and generated module metadata on the manifest. Generated installer libraries and doctor checks derive from it, while install.sh and several orchestration libraries retain explicit authored handoffs. Drift checks cover the seam between those two layers.

One-Page System Data Flow

flowchart TB
  %% User and website
  subgraph U["User (local machine)"]
    Browser["Browser"]
    Terminal["Terminal / SSH client"]
  end

  subgraph W["Wizard Website (Next.js 16) — apps/web"]
    Wizard["Wizard UI (/wizard/*)"]
    InstallRoute["GET /install (302 redirect to raw install.sh)"]
    WebState["State: URL params + localStorage"]
  end

  %% Repo sources
  subgraph R["Repo (source)"]
    Manifest["acfs.manifest.yaml<br/>Modules + install + verify + deps"]
    Generator["packages/manifest<br/>Parser (Zod) + generate.ts"]
    Generated["scripts/generated/*<br/>source-only libraries/harness + doctor/index/checksum data"]
    Installer["install.sh (production one-liner)"]
    Lib["scripts/lib/*<br/>security / doctor / update / services-setup"]
    Configs["acfs/*<br/>zshrc + tmux.conf + onboard lessons"]
    Checksums["checksums.yaml<br/>sha256 for upstream installers"]
    Tests["tests/vm/test_install_ubuntu.sh<br/>Docker integration test"]
  end

  %% Target VPS
  subgraph V["Target VPS (Ubuntu LTS, existing release preserved)"]
    Run["Run install.sh"]
    Verify["Verified upstream installers<br/>(security.sh + checksums.yaml)"]
    AcfsHome["~/.acfs/<br/>configs + scripts + state.json"]
    Commands["Commands<br/>acfs doctor / acfs update / acfs services / acfs services-setup / onboard"]
    Tools["Installed tools<br/>bun/uv/rust/go + tmux/rg/gh + vault + ..."]
    Agents["Agent CLIs<br/>claude / codex / agy"]
    Stack["Stack tools<br/>ntm / mcp_agent_mail / ubs / bv / cass / cm / caam / slb / dcg / ru"]
  end

  %% Website guidance flow
  Browser --> Wizard
  Wizard --> WebState
  Wizard --> InstallRoute
  InstallRoute -->|redirects to| Installer

  %% How users fetch/run the installer
  Terminal -->|curl / bash| Installer
  Terminal -->|SSH| Run

  %% Manifest-driven generation
  Manifest --> Generator --> Generated
  Generated -->|install.sh sources category libraries<br/>and dispatches private module functions| Installer

  %% Installer composition
  Lib --> Installer
  Configs --> Installer
  Checksums --> Installer
  Tests -->|validates| Installer

  %% VPS install results
  Installer --> Run
  Run --> Verify
  Verify --> Tools
  Verify --> Agents
  Verify --> Stack
  Run --> AcfsHome --> Commands

┌─────────────────────────────────────────────────────────────────────────────┐
│                            SOURCE OF TRUTH                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │  acfs.manifest.yaml                                                  │    │
│  │  Tool Definitions • Install Commands • Verification Logic           │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
┌───────────────────────────────────┐   ┌───────────────────────────────────┐
│        CODE GENERATION            │   │        WIZARD WEBSITE             │
│  ┌─────────────────────────────┐  │   │  ┌─────────────────────────────┐  │
│  │ TypeScript Parser (Zod)     │  │   │  │ apps/web/ (Next.js 16)      │  │
│  │ generate.ts                 │  │   │  │ agent-flywheel.com          │  │
│  └─────────────────────────────┘  │   │  └─────────────────────────────┘  │
└───────────────────────────────────┘   └───────────────────────────────────┘
                    │
                    ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                     GENERATED OUTPUTS (REFERENCE)                          │
│  scripts/generated/: 13 source-only category libraries + install_all      │
│  harness + doctor checks + manifest index + schema-1 checksum ledger      │
└───────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                            INSTALLER                                       │
│  install.sh + scripts/lib/*.sh + checksums.yaml (SHA256 verification)     │
│  (category libraries are sourced; install.sh owns production dispatch)      │
└───────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                           TARGET VPS                                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │ 30+ Tools    │  │ zsh + p10k   │  │ AI Agents    │  │ ~/.acfs/     │   │
│  │ Installed    │  │ Shell Config │  │ Claude/Codex │  │ Configurations│  │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘   │
└───────────────────────────────────────────────────────────────────────────┘

Why This Architecture?

Single Source of Truth: The manifest file (acfs.manifest.yaml) defines every tool—its name, description, install commands, and verification logic. When you add or edit a tool in the manifest, the generator automatically updates the generated scripts and manifest-derived checks. The production one-liner installer (install.sh) is still hand-written today, so behavior changes may also require updating install.sh until full migration.

TypeScript + Zod Validation: The manifest parser uses Zod schemas to validate the YAML at parse time. Typos, missing fields, and structural errors are caught immediately during generation—not at runtime on a user's VPS when the installer fails halfway through.

Generated Scripts: Rather than hand-maintaining one installer script per manifest category and keeping them synchronized, the generator produces them from the manifest. This means:

• A consistent, auditable view of manifest-defined install logic (some modules intentionally emit TODOs)
• Consistent error handling and logging across all modules
• A clear path toward future installer integration

Components

The Manifest System

acfs.manifest.yaml is the canonical inventory for generated ACFS modules. It defines their installation and verification metadata; authored orchestration remains responsible for bootstrap, lifecycle, and registered non-generated handoffs.

Manifest Structure

version: 2
name: agentic_coding_flywheel_setup
id: acfs
defaults:
  user: ubuntu
  workspace_root: /data/projects
  mode: vibe

modules:
  - id: base.system
    description: Base packages and sane defaults
    category: base
    run_as: root
    optional: false
    enabled_by_default: true
    generated: true
    phase: 1
    install:
      - apt-get update -y
      - apt-get install -y curl git ca-certificates unzip tar xz-utils jq build-essential
    verify:
      - curl --version
      - git --version
      - jq --version

Each module specifies:

• description: Human-readable name
• category: One of the canonical groups: base, users, filesystem, shell, cli, network, lang, tools, db, cloud, agents, stack, acfs
• install: Commands to run (or descriptions that become TODOs)
• verify: Commands that must succeed to confirm installation

The Generator Pipeline

The TypeScript generator (packages/manifest/src/generate.ts) reads the manifest and produces:

1. Category Libraries (scripts/generated/install_base.sh, install_agents.sh, etc.)

   • One source-only file per category with private module functions
   • Consistent logging and error handling
   • Verification checks after each module
   • Direct execution fails closed because a single category cannot satisfy cross-category dependencies

2. Doctor Checks (scripts/generated/doctor_checks.sh)

   • All verify commands extracted into a runnable health check
   • Tab-delimited format (to safely handle || in shell commands)
   • Reports pass/fail/skip for each module

3. Generated Harness (scripts/generated/install_all.sh)

   • Sources all category libraries
   • Invokes private module functions in global dependency order
   • Sourceable generated-module harness; direct execution refuses because it omits orchestration-owned modules and production dispatcher semantics

4. Runtime Data (scripts/generated/manifest_index.sh, internal_checksums.sh)

   • Deterministic module/category/generated-ownership metadata
   • Closed-grammar schema-1 digests for checksum-controlled runtime scripts

Note: Production install.sh is the only supported installation entry point. It sources the category libraries and dispatches their private functions through its phase runner; it does not call install_all.sh.

To regenerate after manifest changes:

cd packages/manifest
bun run generate        # Generate scripts
bun run generate:dry    # Preview without writing

Why TypeScript for Code Generation?

Shell can parse YAML with yq, but TypeScript + Zod offers:

• Type safety: The parser knows the exact shape of a manifest
• Validation: Zod catches malformed YAML with descriptive errors
• Transformation: Complex logic (sorting by dependencies, escaping) is natural in TypeScript
• Consistency: All generated code follows the same patterns

The generator centralizes the substantially larger Bash output in one reviewed TypeScript implementation. Exact line and file counts are intentionally derived from the current manifest rather than frozen in this document.

Security Verification

ACFS downloads and executes installer scripts from the internet. This is inherently risky—a compromised upstream could inject malicious code. The security verification system mitigates this risk.

How It Works

The checksums.yaml file contains SHA256 hashes for all upstream installer scripts:

# checksums.yaml
installers:
  bun:
    url: "https://bun.sh/install"
    sha256: "a1b2c3d4..."

  rust:
    url: "https://sh.rustup.rs"
    sha256: "e5f6a7b8..."

The security library (scripts/lib/security.sh) provides:

1. HTTPS Enforcement: All installer URLs must use HTTPS. Non-HTTPS URLs fail immediately.

2. Checksum Verification: Before executing a downloaded script, the system:

   • Downloads the content to memory
   • Calculates the SHA256 hash
   • Compares against the stored hash
   • Only executes if they match

3. Verification Modes:

   ./scripts/lib/security.sh --print              # List all upstream URLs
   ./scripts/lib/security.sh --verify             # Verify all against saved checksums
   ./scripts/lib/security.sh --update-checksums   # Generate new checksums.yaml
   ./scripts/lib/security.sh --checksum URL       # Calculate SHA256 of any URL

The uv installer also requires a working sha256sum from coreutils in its clean target-user environment. Immediately before executing uv's verified installer, ACFS checks the verifier with a known SHA256 result using the same system PATH and account. A missing, failing, or incorrect verifier stops the installation before uv can download release archives, and asks you to repair or install coreutils. This applies to both the legacy and generated installers and preserves the installer's stdin.

When Checksums Fail

A checksum mismatch can mean:

1. Normal update: The upstream maintainer released a new version
2. Potential compromise: Someone modified the script maliciously

The verification report distinguishes these cases:

• If multiple checksums fail simultaneously, investigate before updating
• If a single checksum fails after a known release, update is likely safe

To update after verifying a legitimate upstream change:

# Write to a candidate file first: redirecting straight onto checksums.yaml
# truncates it before the script runs, so a single fetch error would leave
# it empty and every verified installer would fail closed.
./scripts/lib/security.sh --update-checksums > /tmp/acfs-checksums.candidate.yaml
diff -u checksums.yaml /tmp/acfs-checksums.candidate.yaml   # Review what changed
cp /tmp/acfs-checksums.candidate.yaml checksums.yaml
git commit -m "chore: update upstream checksums"

Why This Approach?

The curl | bash pattern is controversial but practical. ACFS makes it safer by:

• Verifying content before execution (not just transport via HTTPS)
• Making checksums auditable in version control
• Providing tools to detect and investigate changes
• Failing closed (no execution on mismatch)

This is defense in depth—HTTPS protects transport, checksums protect content.

Omarchy (Arch) support

Omarchy (and Arch Linux generally) is supported by the same one-liner — no separate command required. The installer auto-detects your distribution and adapts:

• pacman instead of apt: system packages and CLI tools install via pacman.
• Your existing starship config is preserved: if you already have a customized starship.toml, ACFS leaves it alone rather than overwriting it.
• No oh-my-zsh / powerlevel10k on Arch: Arch users typically have an opinionated shell setup already, so the installer skips the oh-my-zsh + powerlevel10k phase instead of clobbering your prompt.
• apt-only modules stop early under --only / --skip: a filtered run executes the manifest modules directly rather than the pacman-aware default path. The modules that can only install with apt (base.system, shell.zsh, cli.modern, lang.go, network.tailscale, tools.vault, db.postgres18) stop before changing anything and print the pacman command to run instead. db.postgres18 instead points to an unfiltered run: its check only recognizes the Ubuntu packages, and the default Arch path installs and initializes PostgreSQL with pacman.

Everything else — language runtimes, AI agents, and the flywheel tool stack — installs identically to Ubuntu.

Cloud agent environments

The public cloud agent setup guide selects the right recipe for your provider. Claude Code and ChatGPT / Codex have hosted test evidence; Amp Orbs, Devin and Grok Bot have documentation-based recipes awaiting hosted acceptance. Meta Muse needs shell/runtime and persistence checks before an installation recipe can be accepted. The installer retains its original filename and supports claude, codex and provider-neutral generic modes.

Prefer to hand the setup to a browser agent? Use Copy full instructions near the top of the guide, or share its complete ChatGPT / Codex Markdown brief. The Markdown is the exact copy-button content, including scripts, screenshot references and verification steps. Choose agent=claude, codex, amp, devin, grok, muse or generic; omitting agent defaults to Claude. The guide's Open Markdown link follows your selected provider.

Claude Code on the web

Claude Code on the web runs cloud sessions on a disposable Ubuntu 24.04 VM. ACFS uses scripts/claude-code-web-setup.sh to install prebuilt agent-facing tools during setup, without provisioning users, upgrading the OS or starting background services. The cloud guide walks through it with copy buttons.

Set it up: in claude.ai/code open the environment menu, choose Add cloud environment (or edit one), set Network access to Full (recommended), and paste this as the Setup script:

#!/bin/bash
(
acfs_cloud_setup="$(curl -q -fsSL --proto '=https' --proto-redir '=https' --connect-timeout 5 --max-time 20 -A 'acfs (+https://github.com/Dicklesworthstone/agentic_coding_flywheel_setup)' -H 'Accept-Encoding: identity' https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/claude-code-web-setup.sh)" || { printf '%s\n' 'ACFS cloud bootstrap download failed; tools were not installed. Check network access and retry.' >&2; exit 0; }
printf '%s\n' "$acfs_cloud_setup" | bash
)

The bootstrap downloads completely before it runs, with a 20-second transfer limit. If that download fails, Claude reports the failure and still starts the session. Full access enables the public binary mirror. Custom and restricted-mode behavior are described below. Pasting the whole script into the field works too.

How it behaves:

• Every prebuilt bundle is checked against the repository's cloud-mirror.json before extraction. A mismatch skips the tool. All tools, including JSM, are hash-pinned.
• Tool jobs run in parallel with a maximum 180-second deadline covering downloads and both existing/final binary checks, plus up to two seconds for termination. This keeps setup inside the roughly five-minute caching window under normal VM operation. No compiler is invoked. Later sessions start from the snapshot with the tools already installed.
• The script always exits 0, because a failing setup script stops the session from starting. Anything that did not install is listed in the summary, in ~/.acfs/cloud/setup.log, and in the guide below.
• It writes a managed block into ~/.claude/CLAUDE.md (or $CLAUDE_CONFIG_DIR/CLAUDE.md), which cloud sessions load as user instructions, so Claude knows which flywheel tools exist and how to call them. Content outside the block is preserved. If existing managed markers are incomplete, setup leaves the file untouched and logs the retained replacement guide's location.
• With a custom ACFS_CLOUD_ROOT, new Claude Agent Mail MCP registrations keep their archive in that writable root, preserving an explicit STORAGE_ROOT or XDG_DATA_HOME. The generated CLI recipes and rerun command retain the same setup-selected archive when a later task no longer has those environment overrides; relative setup paths are resolved from the setup directory. Explicit task-time STORAGE_ROOT values still win. Setup does not copy DATABASE_URL credentials into the registration or guide. Re-runs repair the exact old ACFS entry that launched mcp-agent-mail without arguments, retaining a private config backup. Existing registrations retain their storage configuration; use the guide's CLI recipe if a retained registration points at an unwritable location.

Left out on purpose: everything in install.sh that provisions a long-lived machine (users, zsh theming, the Ubuntu upgrade, systemd services, Tailscale, PostgreSQL, Vault, cloud CLIs), plus ntm (no interactive terminal to drive), dcg (it installs a user-level Claude Code hook, and cloud sessions only run hooks from the repository's .claude/settings.json), rch (needs SSH build workers), and caam, ru, slb.

Options, set inline so the setup script itself sees them (for example curl -fsSL … | ACFS_CLOUD_TOOLS="br bv am ubs ast-grep" bash). Selecting UBS automatically includes ast-grep so its structural checks are available without a first-scan download:

When choosing a custom ACFS_CLOUD_ROOT in generic mode, replace the $HOME paths in the task instructions with that root. Its guide and log are <root>/.acfs/cloud/AGENTS.md and <root>/.acfs/cloud/setup.log. The generated guide supplies the exact PATH and data commands, including Agent Mail's command-local storage setting.

Once the setup script is available, reruns reuse working tools without downloading the manifest or bundles. If a tool is missing, fails its version check, or ACFS_CLOUD_REINSTALL=1 is set, parallel install jobs share one manifest download within their existing deadlines. Download failures remain visible and never trigger source builds.

Public prebuilt mirror: every default tool, including ast-grep, JSM and JFP, comes from https://downloads.agent-flywheel.com/acfs-cloud/v1. No login, GitHub token or repository ownership is needed. Select Full network access, or Custom allowing raw.githubusercontent.com and downloads.agent-flywheel.com. Bundles are pinned by SHA256 in cloud-mirror.json, use content-addressed URLs, and are checked before extraction and executable verification. Setup never runs upstream installers or builds from source.

Trusted/degraded mode: when the mirror cannot be reached, setup tries the exact public artifact pinned in the same manifest. JSM uses a vendor-verified copy on public GitHub, with its original checksum and upstream URL retained. UBS uses a complete public copy of the mirror bundle, including its release-pinned modules and helpers, so scans need no module downloads after setup. The environment's GitHub proxy may block these downloads too, so Trusted does not guarantee all tools. Existing working tools remain available, failures explain the Full/Custom setting in the summary, and session startup continues.

The bundles target Linux x86_64. Each executable must successfully return its version before installation. JFP uses the baseline x64 release asset, verified on both Ivy Bridge without AVX2 and EPYC with AVX2. The publisher requires that asset and refuses to substitute a modern-only build.

Maintainer refresh: python3 scripts/cloud-mirror-publish.py --stage /path/on/large-disk/acfs-cloud --output /path/to/new-candidate.json --publish discovers latest releases with authenticated gh, verifies release checksums and pinned Minisign signatures where published, bundles Linux x86_64 executables, uploads with authenticated Wrangler, and verifies each public download. It requires Python 3.10+, gh, minisign, and wrangler; these credentials are needed only by the maintainer. Review the candidate, smoke-test on Ubuntu 24.04, and commit it as cloud-mirror.json. Repeated runs reuse downloaded artifacts and skip matching remote bundles. Staging is retained for inspection. A failed tool aborts manifest publication; it cannot silently disappear from the install set.

Use --tools br bv to refresh a subset while retaining every other entry from the committed manifest. Partial refreshes require its existing base URL. Refreshing JSM also publishes its verified vendor archive to the public cloud-binaries-v1 prerelease. Assets include the source checksum in their names, are never replaced, and must pass both GitHub's digest check and anonymous download verification before the candidate manifest is written. This carrier does not change ACFS's normal latest release. When mirroring to another R2 bucket/domain, --base-url supplies the public prefix and --bucket supplies the destination bucket; the URL path becomes the object prefix.

ChatGPT / Codex cloud environments

The same public bundles work in a Linux x86_64 Codex cloud environment. In Work in → Cloud, create or edit an environment and put this in its Install script:

#!/bin/bash
(
set -o pipefail
acfs_cloud_root="$(git rev-parse --show-toplevel)" || exit 1
acfs_cloud_setup="$(curl -q -fsSL --proto '=https' --proto-redir '=https' --connect-timeout 5 --max-time 20 -A 'acfs (+https://github.com/Dicklesworthstone/agentic_coding_flywheel_setup)' -H 'Accept-Encoding: identity' https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/claude-code-web-setup.sh)" || { printf '%s\n' 'ACFS cloud bootstrap download failed; tools were not installed. Check network access and retry.' >&2; exit 1; }
printf '%s\n' "$acfs_cloud_setup" | ACFS_CLOUD_SKILL_DIR="$acfs_cloud_root/.agents/skills/acfs-cloud-tools" ACFS_CLOUD_AGENT=codex ACFS_CLOUD_ROOT="$acfs_cloud_root/.acfs-cloud" bash || exit 1
acfs_cloud_exclude="$(git rev-parse --git-path info/exclude)" || exit 1
mkdir -p "$(dirname "$acfs_cloud_exclude")" || exit 1
printf '\n/.acfs-cloud/\n/.agents/skills/acfs-cloud-tools/\n' >> "$acfs_cloud_exclude"
) || exit 1

Enable internet access and add raw.githubusercontent.com and downloads.agent-flywheel.com to Additional allowed domains. These public downloads need no secrets or ownership of the tool repositories. The recipe installs into the writable repository workspace because hosted home/config paths can be read-only, and excludes its data directory through local Git metadata. It preserves HOME and CODEX_HOME. Review <repo>/.acfs-cloud/.acfs/cloud/setup.log, then Publish the prepared environment. After changing its setup, Republish for new tasks. See OpenAI's current cloud environment guide.

Save these instructions in the environment's Start skill and include them at the start of each new task. Our hosted checks reused all eleven executables but did not automatically load the saved Start skill or generated repository skill; explicitly loading the guide and setting PATH works:

Find the repository root with git rev-parse --show-toplevel.
Read <repo>/.acfs-cloud/.codex/AGENTS.md for the installed flywheel tools and <repo>/.acfs-cloud/.acfs/cloud/setup.log for failures.
In each task shell, run acfs_cloud_root="$(git rev-parse --show-toplevel)/.acfs-cloud"; export PATH="$acfs_cloud_root/.local/bin:$PATH" before using the tools.
Follow the guide's CASS_DATA_DIR, CASS_MEMORY_HOME and JFP_HOME exports in each task shell so search data, memory and prompt caches use the writable workspace; preserve existing overrides and keep any XDG_DATA_HOME/XDG_CONFIG_HOME writable.
Before using Agent Mail with a read-only HOME, follow the guide's command-scoped STORAGE_ROOT recipe; reuse existing configuration and preserve DATABASE_URL.
Before using JSM with a read-only HOME, follow the guide's command-scoped XDG recipe; reuse existing configuration and check skill installation targets separately.
Keep JSM_DISABLE_SELF_UPDATE=1 in each task shell so ordinary JSM commands retain the manifest-pinned executable; use verified cloud setup for tool refreshes.
Before using MS, follow the guide's local initialization and indexing steps in a writable project; reuse existing .ms/MS_ROOT/MS_CONFIG state.
Check br --version, bv --version, ubs --version and jsm --version before starting work.
Use br ready --json and bv --robot-triage; never open their interactive TUIs.

Codex mode preserves existing instructions outside its managed block. Without a custom root it uses $CODEX_HOME/AGENTS.md or ~/.codex/AGENTS.md; a nonempty AGENTS.override.md takes precedence, so setup warns. The workspace recipe also creates .agents/skills/acfs-cloud-tools/SKILL.md in Codex's documented repository skill location; an existing skill at that path is preserved. Reading that skill loads the separate guide and configures PATH. Automatic hosted catalog discovery failed in our checks: a fresh task still omitted it after removing its Git exclusion, so changing exclusions is not a proven fix. Use the explicit startup instructions above. See OpenAI's instruction discovery rules. Agent Mail is available as a CLI; this setup does not configure or claim hosted MCP support. Local Codex MCP configuration and ChatGPT's remote MCP connections are different surfaces; see OpenAI's MCP guide.

If your UI instead has Setup script and Maintenance script, it uses the legacy environment workflow. Put the install command in Setup script; avoid reinstalling in Maintenance script on every cached resume. Configure task-phase internet separately if tools need online access after setup.

Verification boundary: both installer modes are tested on Ubuntu 24.04, including real public downloads. On 2026-10-08, a fresh Claude-hosted Full session pinned to 4a0e6bfa792ce73ad4c69847755ecd64384288c2 installed all ten tools in 12 seconds; all eleven versions passed, the guide loaded automatically, and Agent Mail's stdio MCP health check passed. On 2026-10-09, a cold default-Trusted Claude session pinned to 31c8180860f9ed461d9843d6ed298939a5b3ea74 installed all ten tools through public fallbacks in 53 seconds; all eleven versions, automatic instructions and actual Agent Mail MCP health passed. That run's first UBS helper download failed TLS; its release-hash-verified recovery was tested separately. The later complete UBS fallback removes that lazy module download, but has not been rerun in that hosted session. Codex hosted installation took 6 seconds at 140a845d; fresh published tasks reused all eleven executables, including after the repository-skill update at 4bdbf5a7. A task that explicitly loaded the guide configured PATH and passed all eleven probes. Automatic Codex skill loading remains open. These times describe the pinned earlier recipes, not a fresh hosted acceptance of later changes. The script reports individual failures but exits zero; successful session startup alone does not prove every tool installed. Default UBS exit 0 can include warnings; inspect its report or use --ci --fail-on-warning for a warning-strict check.

Other Linux cloud agents

The provider-neutral template writes $HOME/.acfs/cloud/AGENTS.md and does not change agent configuration or register MCP servers:

#!/bin/bash
(
set -o pipefail
acfs_cloud_setup="$(curl -q -fsSL --proto '=https' --proto-redir '=https' --connect-timeout 5 --max-time 20 -A 'acfs (+https://github.com/Dicklesworthstone/agentic_coding_flywheel_setup)' -H 'Accept-Encoding: identity' https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/claude-code-web-setup.sh)" || { printf '%s\n' 'ACFS cloud bootstrap download failed; tools were not installed. Check network access and retry.' >&2; exit 1; }
printf '%s\n' "$acfs_cloud_setup" | ACFS_CLOUD_AGENT=generic bash
) || exit 1

Include these instructions in each task:

Read $HOME/.acfs/cloud/AGENTS.md and $HOME/.acfs/cloud/setup.log before starting work.
In each task shell, run export PATH="$HOME/.local/bin:$PATH".
If using a custom writable data root, follow the guide's CASS_DATA_DIR, CASS_MEMORY_HOME and JFP_HOME exports in each task shell; preserve existing overrides and keep any XDG_DATA_HOME/XDG_CONFIG_HOME writable.
Before using Agent Mail with a read-only HOME, follow the guide's command-scoped STORAGE_ROOT recipe; reuse existing configuration and preserve DATABASE_URL.
Before using JSM with a read-only HOME, follow the guide's command-scoped XDG recipe; reuse existing configuration and check skill installation targets separately.
Keep JSM_DISABLE_SELF_UPDATE=1 in each task shell so ordinary JSM commands retain the manifest-pinned executable; use verified cloud setup for tool refreshes.
Before using MS, follow the guide's local initialization and indexing steps in a writable project; reuse existing .ms/MS_ROOT/MS_CONFIG state.
Check br --version, bv --version, ubs --version and jsm --version; report missing tools from the setup log.
Use the existing repository tracker with br ready --json and bv --robot-triage. Never open their interactive TUIs.
Agent Mail is available as a CLI. This setup does not configure this agent's MCP servers.

Requirements: Linux x86_64 with compatible runtime libraries, Bash, Python 3, curl, tar and GNU timeout, plus a writable data root. Ubuntu 24.04 has full install checks. On 25 October 2026, all eleven current executables also passed offline version checks in a clean Debian 12 x86_64 container with glibc 2.36; this is executable startup evidence, not a Debian installation or hosted-provider test. If you set ACFS_CLOUD_ROOT, use that root instead of $HOME in these instructions. Inspect the setup log and each version command to confirm the installed tools work.

For a custom data root, follow the generated guide's CASS_DATA_DIR and CASS_MEMORY_HOME exports so search data and memory also use the writable workspace, and its JFP_HOME export for prompt caching. These preserve existing overrides and an explicit XDG_DATA_HOME; configured state directories must be writable. JFP also honors XDG_CONFIG_HOME, which takes precedence and must be writable. Provider HOME and configuration are preserved.

Keep JSM pinned: the generated task-shell command exports JSM_DISABLE_SELF_UPDATE=1, and its JSM command examples apply the same opt-out. Otherwise even an ordinary command such as jsm config show can automatically replace the verified binary with a newer vendor release. Saved JSM preferences stay unchanged. For an intentional refresh or to restore the reviewed binary after an automatic update, run the verified cloud setup with ACFS_CLOUD_REINSTALL=1; ordinary reruns reuse working binaries. Existing repository skills are preserved, so use the updated generated guide if a saved skill predates this setting. Avoid jsm update in the pinned environment.

Agent Mail without MCP: the generated guide includes a CLI session recipe using am macros start-session, captures the returned agent name, and reads messages with am robot inbox --include-bodies --json. It also shows how to reserve a specific edit path and release only that reservation. Custom-root recipes apply the same command-scoped storage defaults while preserving DATABASE_URL. These operations need no background service; agents must share the same mailbox to coordinate across tasks. Separate provider VMs do not share local mail automatically.

MS needs project state before it can search skills. In a writable project, run ms init --robot once, then ms index <skill-directory> --robot and ms search "query" --robot. Replace <skill-directory> with the directory containing your skills, such as .agents/skills. Reuse existing .ms, MS_ROOT or MS_CONFIG state; with configured overrides, skip this initialization recipe. Avoid --global on a read-only HOME and --force when preserving existing state. Setup only installs MS; it leaves project initialization and skill indexing to the task that needs them.

• Amp Orbs: merge the command into executable .agents/setup, or use the project's Pre-setup Script. Do not install dependencies in .agents/resume. Amp documents Debian 12; the current binaries pass the clean Debian 12 version checks above, while Amp-hosted installation, instruction loading and snapshot persistence remain unverified. Setup does not need personal GitHub credentials.
• Devin: add a Linux blueprint run step to initialize or maintenance and task instructions to knowledge. Verify a fresh snapshot. PATH exports do not persist between blueprint steps unless written to $ENVRC; explicit task-shell exports avoid assuming persistence.
• Grok Bot: Enterprise Team Setup runs shell-script manifest entries as the computer user on every Linux team computer. Consumer setup access, binary compatibility and hosted persistence remain unverified. Grok Build CLI and chat Build Mode are different products.
• Meta Muse: Meta documents a persistent Linux VM with Sentinel-controlled access. A usable startup hook, CPU/runtime compatibility and hosted installation have not been verified. Muse Code is the separate terminal/CI agent.

The Installer

The installer is the heart of ACFS—a modular Bash script that transforms a fresh Ubuntu or Arch-based machine into a fully-configured development environment.

Usage

Full vibe mode (recommended for throwaway VPS):

{ acfs_installer="$(curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh")" || acfs_installer="$(curl -fsSL "https://cdn.jsdelivr.net/gh/Dicklesworthstone/agentic_coding_flywheel_setup@main/install.sh")"; } && printf '%s\n' "$acfs_installer" | bash -s -- --yes --mode vibe

Interactive mode (asks for confirmation):

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash

Safe mode (no passwordless sudo, agent confirmations enabled):

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash -s -- --mode safe

Installer Modes

Installation Phases

graph TD
    %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%

    A["Phase 1: User Setup<br/><small>Create ubuntu user, migrate SSH keys, sudo</small>"]
    B["Phase 2: Filesystem<br/><small>/data/projects, ~/.acfs layout</small>"]
    C["Phase 3: Shell Setup<br/><small>zsh, oh-my-zsh, powerlevel10k</small>"]
    D["Phase 4: CLI Tools<br/><small>ripgrep, fzf, lazygit, Tailscale, etc.</small>"]
    E["Phase 5: Language Runtimes<br/><small>bun, uv, rust, go, nvm</small>"]
    F["Phase 6: AI Agents<br/><small>claude, codex, agy</small>"]
    G["Phase 7: Cloud & Database<br/><small>PostgreSQL, vault, wrangler, supabase, vercel</small>"]
    H["Phase 8: Flywheel Stack<br/><small>ntm, agent mail, br, bv, ubs, dcg, ru, etc.</small>"]
    I["Phase 9: Finalize<br/><small>Deploy acfs.zshrc, tmux.conf, agent guide</small>"]
    J["Post-install smoke test<br/><small>critical checks; then run acfs doctor</small>"]

    A --> B --> C --> D --> E --> F --> G --> H --> I --> J

    classDef phase fill:#e8f5e9,stroke:#81c784,stroke-width:2px,color:#2e7d32
    class A,B,C,D,E,F,G,H,I,J phase

Key Properties

Claude Code Settings Written at Install

The installer provisions a few keys in ~/.claude/settings.json, always merging non-destructively (a value you have already set is never overridden):

Resume Capability

The installer tracks progress in ~/.acfs/state.json. Re-run the same command with --resume after fixing a failed dependency, privilege problem, or interrupted installation. Completed phases are checked against the selected modules' live verification results before they can be skipped. Incomplete phases retry their component checks, so working components are kept and missing or broken ones are repaired. This also recovers older installations whose completion records were written despite a failed step; do not delete the state file to recover them.

Required step failures remain recorded until a successful retry or verified recovery resolves them. Optional failures remain visible without blocking an otherwise successful installation; an optional module explicitly requested with --only must succeed. Final success requires the selected essential components to pass verification, including for targeted installations.

To force a fresh reinstall of all tools:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash -s -- --yes --mode vibe --force-reinstall

Pre-Flight Check

Before running the full installer, validate your system:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/preflight.sh" | bash
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/preflight.sh" | bash -s -- --json
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/preflight.sh" | bash -s -- --format toon
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/preflight.sh" | bash -s -- --network=skip

This checks:

• OS compatibility (Ubuntu 22.04+ or Arch-family: Arch, Omarchy; supported LTS releases stay in place unless an upgrade is explicitly requested)
• Architecture (x86_64 or ARM64)
• Memory and disk space (warns below 4GB RAM; fails below 20GB free disk)
• Network connectivity to required URLs
• Cached checksums.yaml availability for verified upstream installers
• APT lock status
• Potential conflicts (nvm, pyenv, existing ACFS)

Network checks performed:

For checksum-refresh review, compare a generated candidate without changing checksums.yaml:

candidate="/tmp/acfs-checksums.$$.candidate.yaml"
./scripts/lib/security.sh --update-checksums > "$candidate"
./scripts/preflight.sh --checksum-candidate "$candidate"

Common preflight failures:

Console Output

The installer uses semantic colors for progress visibility:

[1/8] Installing essential packages...     # Blue: progress steps
    Installing zsh, git, curl...           # Gray: details
⚠️  May take a few minutes                 # Yellow: warnings
✖ Failed to install package               # Red: errors
✔ Shell setup complete                    # Green: success

Optional Ubuntu Release Upgrade

A no-flags install keeps supported Ubuntu 22.04 and 24.04 LTS hosts on their current release. Non-root users with sudo and Ubuntu 24.04 Docker/WSL environments can install ACFS without opting into an OS upgrade.

Pass --target-ubuntu=26.04 to explicitly request an upgrade to Ubuntu 26.04 LTS. An OS upgrade requires a root-run installer on a host that can reboot; it is separate from installing or updating the ACFS tools.

How it works:

1. Detects your current Ubuntu version
2. Calculates a supported upgrade path (e.g., 24.04 → 26.04 LTS)
3. Performs sequential do-release-upgrade operations
4. Reboots after each upgrade (handled automatically)
5. Resumes via systemd service after reboot
6. Continues ACFS installation once at target version

Expected timeline:

• Each version hop takes 30-60 minutes
• Multiple LTS hops take longer; the path must be offered by Ubuntu's stable release upgrader
• SSH sessions disconnect during reboots (reconnect to monitor)

To explicitly request the 26.04 LTS upgrade:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash -s -- --yes --mode vibe --target-ubuntu=26.04

To suppress an explicit upgrade request:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash -s -- --yes --mode vibe --target-ubuntu=26.04 --skip-ubuntu-upgrade

--skip-ubuntu-upgrade wins regardless of flag order. Neither this flag nor an ordinary no-target install bypasses an active system upgrade checkpoint: normal installation remains blocked until the unfinished upgrade is resolved. Inspect the checkpoint and resume logs before retrying; keep the recovery state intact.

Monitoring upgrade progress:

# Check current status
/var/lib/acfs/check_status.sh

# View upgrade logs
journalctl -u acfs-upgrade-resume -f

# View detailed logs
tail -f /var/log/acfs/upgrade_resume.log

Important notes:

• Create a VM snapshot before upgrading (recommended but not required)
• Upgrades cannot be undone without restoring from snapshot
• The system will reboot multiple times automatically
• Ubuntu 25.10 is supported only as a recovery source when explicitly upgrading to 26.04 LTS; it is not an upgrade destination
• Reconnect via SSH after each reboot to monitor progress

The Update Command

After installation, keeping tools current is handled by acfs-update. It provides a unified interface for updating all installed components.

Usage

acfs-update                  # Update apt, runtimes, shell, agents, cloud CLIs, and stack tools
acfs-update --agents-only    # Only update coding agents
acfs-update --runtime-only   # Only update runtimes (bun, rust, uv, go)
acfs-update --dry-run        # Preview changes without making them
acfs-update --yes --quiet --no-self-update
                             # Automated mode that avoids changing the ACFS tree itself
acfs-update --bootstrap-self-update
                             # Explicitly convert a non-git or incomplete install into a git checkout

--bootstrap-self-update replaces ACFS repository files with origin/main. Copy local files elsewhere or commit local edits before opting in. Routine updates leave non-git and incomplete Git installs untouched.

The control-plane boundary: with --no-self-update (the shipped nightly timer's default), automated runs update your stack tools but never ACFS itself -- neither the git checkout nor the deployed runtime copies under ~/.acfs (bin/acfs, bin/acfs-update, scripts/lib/*.sh). The control plane therefore needs its own periodic refresh: run acfs-update without --no-self-update from time to time, or git pull --rebase the checkout and then run acfs-update --shell-only to redeploy the runtime copies. acfs doctor warns (updates.runtime_skew) when the checkout and the deployed runtime disagree, so a stack kept current by the nightly cannot silently outrun a stale dispatcher.

Temp space: if TMPDIR (default /tmp) refuses a test write, because it is full or over a per-user tmpfs quota, acfs-update moves the run to the first of ACFS_UPDATE_TMPDIR, /data/tmp, /var/tmp and ~/.cache/acfs/tmp that accepts one. Verified installers are staged in a system directory instead of TMPDIR: /tmp, or /var/tmp when /tmp refuses the write.

What Gets Updated

Options

Category Selection:

--apt-only       Only update system packages
--agents-only    Only update coding agents
--cloud-only     Only update cloud CLIs
--shell-only     Only update shell tools (OMZ, P10K, plugins, Atuin, Zoxide)
--runtime-only   Only update runtimes (bun, rust, uv, go)
--stack          Include Agent Flywheel stack tools (enabled by default)

Skip Categories:

--no-apt         Skip apt updates
--no-agents      Skip agent updates
--no-cloud       Skip cloud CLI updates
--no-shell       Skip shell tool updates
--no-runtime     Skip runtime updates (bun, rust, uv, go)

Behavior:

--force            Install missing tools (not just update existing)
--dry-run          Preview changes without making them
--yes, -y          Non-interactive mode (skip prompts)
--quiet, -q        Minimal output (only errors and summary)
--verbose, -v      Show detailed command output
--abort-on-failure Stop on first failure (default: continue)

Per-Tool Version Holds

When a single tool ships a regression, hold just that tool instead of pausing the whole nightly. Every hold records an owner, a reason, and an optional expiry, so a hold is a visible decision rather than silent version drift:

acfs hold br --version 0.4.1 --reason "0.5.2 cannot read existing beads DBs" --expiry 2026-09-15
acfs holds        # list holds (also surfaced by `acfs doctor` and every update summary)
acfs unhold br    # release the hold

Held tools are skipped by every update run with the owner/reason/expiry named in the log. Expired holds warn and are ignored. Holds live in ~/.acfs/holds.yaml.

Post-Install Verification and Rollback

Before a verified installer replaces a tool binary, the previous binary is retained at <binary>.prev. After the install, a smoke check probes the fresh binary with a per-tool argument (update_tool_smoke_probe in scripts/lib/update.sh: fsfs version, mdwb --help, pfr --help) or, for tools without an entry, the chain --version → --help → version. Every probe is headless-safe and runs with stdin detached under a 20 s ceiling. Verdicts:

• healthy — a probe exited 0.
• unsupported — every probe was rejected as an unknown argument (usage error). The binary ran, so it is kept and logged as POST-INSTALL VERIFICATION UNAVAILABLE; no rollback, no backoff.
• broken — a probe timed out, could not execute, died by signal, or failed without a usage-style rejection (crash, traceback, missing runtime). The previous binary is restored atomically and the failure is recorded in ~/.local/state/acfs/update-rollback.state so nightly runs back off instead of reinstalling the same broken release every night.

acfs doctor reports rolled back tools; acfs-update --force retries immediately. A backoff also ends as soon as the tool's pinned installer changes or its GitHub repo publishes a new release, because neither has failed yet.

acfs-update exit codes distinguish partial from total failure: 0 all succeeded, 1 total failure (nothing updated), 2 partial failure (some tools updated, some failed).

Logs

Update logs are automatically saved to ~/.acfs/logs/updates/ with timestamps:

# View most recent log
cat ~/.acfs/logs/updates/$(ls -1t ~/.acfs/logs/updates | head -1)

# Follow a running update
tail -f ~/.acfs/logs/updates/$(ls -1t ~/.acfs/logs/updates | head -1)

Why Separate from the Installer?

The installer transforms a fresh VPS. The update command maintains an existing installation. Separating them allows:

• Focused updates: Update just agents without touching system packages
• Dry-run previews: See what would change before committing
• Skip flags: Temporarily exclude categories that are working fine
• Stack control: Stack updates are included by default; skip with --no-stack
• Automated updates: Run via cron with --yes --quiet

ACFS CLI Commands

After installation, the acfs command provides a unified interface for managing your environment. Each subcommand is designed to be fast, informative, and scriptable.

Quick Reference

acfs info                    # Lightning-fast system overview
acfs cheatsheet              # Discover installed aliases
acfs dashboard generate      # Generate HTML status page
acfs doctor                  # Health checks
acfs newproj                 # Create a new project (TUI or CLI)
acfs agents update           # Regenerate the flywheel agent guide (ACFS-owned)
acfs agents install --help   # Explicitly deploy the guide (never overwrites)
acfs update                  # Update all tools
acfs holds                   # List per-tool version holds (acfs hold/unhold to manage)
acfs services status         # Check Agent Mail, CM, and CASS daemons
acfs services-setup          # Configure agent credentials
acfs continue                # View upgrade progress after reboot
acfs installer-cache build   # Cache checksum-pinned installer entrypoints

acfs installer-cache build — Verified Installer Entrypoint Cache

Build a portable acfs-installer-cache/ directory containing the checksum-pinned upstream installer scripts selected from acfs.manifest.yaml. On Ubuntu, pass either that directory or its parent to a later installation:

acfs installer-cache build --output /mnt/acfs-cache
./install.sh --yes --verified-installer-cache /mnt/acfs-cache

Explicit cache selection is fail-closed: if a required cached entrypoint is missing, stale, malformed, for another Ubuntu/architecture target, or does not match the current manifest and checksums.yaml, ACFS refuses it instead of fetching that entrypoint live.

This is not a complete offline installer. The cached entrypoint scripts still need network access for release archives, package registries, Git repositories, APT packages, and other transitive payloads. The initial ACFS bootstrap is also separate; use --bootstrap-archive for that layer. The roadmap below retains full pre-downloaded package bundles as future work.

acfs newproj — New Project Wizard

Create a new project directory with ACFS defaults (git init, optional br/beads, Claude settings, AGENTS.md). The interactive wizard is recommended for beginners. Its file creation requires Python 3. It rejects symlink destinations and parent directories, and creates files exclusively so existing or concurrently created files are preserved. New directories and files are capped at 0755 and 0644; a stricter caller umask still applies. A failed write leaves the partial file in place for inspection; it does not roll back the project. While the wizard remains open, Retry is bound to the original directory, not just its name. If that directory is moved or replaced, restore it to retry, or choose another directory; the replacement cannot inherit completed steps from the old project.

Interactive wizard (recommended):

acfs newproj --interactive
acfs newproj -i
acfs newproj -i myapp         # Prefill project name

The wizard guides you through:

• Project naming and location
• Tech stack detection/selection
• Feature selection (br/beads, Claude settings, AGENTS.md, UBS ignore)
• AGENTS.md customization preview

Wizard diagnostics use private session files (mode 0600) and create new log directories with mode 0700, without changing your shell's umask or existing directory permissions. Repeated sessions get distinct files. Edited AGENTS.md contents remain in the project; state logs record only their length.

    ╔═══════════════════════════════════════════════════════╗
    ║                                                       ║
    ║      █████╗  ██████╗ ███████╗ ███████╗                ║
    ║     ██╔══██╗██╔════╝ ██╔════╝ ██╔════╝                ║
    ║     ███████║██║      █████╗   ███████╗                ║
    ║     ██╔══██║██║      ██╔══╝   ╚════██║                ║
    ║     ██║  ██║╚██████╗ ██║      ███████║                ║
    ║     ╚═╝  ╚═╝ ╚═════╝ ╚═╝      ╚══════╝                ║
    ║                                                       ║
    ║          Agentic Coding Flywheel Setup                ║
    ║                                                       ║
    ╚═══════════════════════════════════════════════════════╝

This wizard will help you set up a new project with:

  ✓ Project directory structure
  ✓ Git repository initialization
  ✓ AGENTS.md for AI coding assistants
  ✓ Beads issue tracking (optional)
  ✓ Claude Code settings (optional)

──────────────────── Review & Confirm ────────────────────
                                              Step 7 of 9

Please review your selections before creating the project.

Project Summary
──────────────────────────────────────────────────────────
  Name:       myapp
  Location:   /home/user/projects/myapp
  Tech:       Node.js, TypeScript

Features
──────────────────────────────────────────────────────────
  ✓ Beads tracking
  ✓ Claude Code settings
  ✓ AGENTS.md
  ✓ UBS ignore

Files to Create
──────────────────────────────────────────────────────────
myapp/
├── .git/
├── AGENTS.md
├── .beads/
│   └── beads.db
├── .claude/
│   └── settings.local.json
├── .ubsignore
├── README.md
└── .gitignore

Options:
  [Enter/c]   Create project
  [e]         Edit selections (go back)
  [q/Esc]     Cancel

CLI mode (automation):

acfs newproj myapp
acfs newproj myapp /custom/path
acfs newproj myapp --no-br

CLI mode's initial commit includes only the files it creates and known shareable Beads configuration files. It respects Git ignore rules, keeps Claude's local settings private, and leaves unrelated staged and untracked work out of the commit. If creation fails, the partial project stays on disk for inspection.

Reviewed bootstrap (plan first, then apply; needs Python 3 and runs no agents):

acfs newproj --guided                                    # choose, review, save and create in the terminal
acfs newproj --plan myapp --preset first-project --stack python | tee myapp-plan.json
acfs newproj --plan myapp /custom/path --with git,readme,gitignore,agents
acfs newproj --apply myapp-plan.json --yes               # create exactly what the plan lists
acfs newproj --apply myapp-plan.json --yes --resume      # continue an interrupted apply

• --plan, --apply or --guided must come first; otherwise the arguments are read as CLI mode.
• --plan prints the plan as JSON and creates nothing. Features are always explicit: --preset first-project (git, readme, gitignore, agents, starter, ci, prompt) or --with a comma-separated list of those plus beads and agent-mail. --stack is python (the default) or typescript; --beads adds local Beads initialization. The directory defaults to $ACFS_PROJECTS_DIR/<name> (/data/projects/<name>).
• --agent-mail URL also registers the project with that Agent Mail service and configures project-local Claude MCP; --agent-mail-token-env NAME reads the token from that variable without storing it, and --agent-mail-clients claude,codex,gemini chooses which clients to configure.
• --apply regenerates the plan and refuses one that was edited or that this ACFS version would generate differently. It never overwrites existing files.

Opt-in GitHub publication and ru registration

To create a GitHub repository and publish the initial project, include both an explicit visibility and an exact OWNER/REPO destination in the reviewed plan. Replace OWNER with your GitHub account or organization. Add --ru if you also want repo_updater to manage the new repository:

acfs newproj --plan myapp --preset first-project --stack python \
  --github=private --github-repo OWNER/myapp --ru > myapp-plan.json

# Inspect the complete plan, including the files that will be published.
cat myapp-plan.json
acfs newproj --apply myapp-plan.json --yes

Use --github=public only when you intend to make those files public. Omitting --github preserves local-only creation; configuration variables never enable publication or registration implicitly. --github-repo is required with --github, and --ru requires GitHub publication. The selected preset or --with list must include git. These options belong to the reviewed --plan workflow; the older positional CLI and --interactive TUI remain local-only. acfs newproj --guided offers the same choices with none as the GitHub default and a separate opt-in for ru.

Planning remains offline and creates nothing. The plan records repository visibility and destination, the initial commit and push to main, the exact publication file list, and any ru configuration/state directories that will be written. Applying with --yes, or choosing create after guided review, authorizes those specific operations. It does not authorize later agent pushes; the generated AGENTS.md keeps its explicit-permission requirement.

Before applying, install gh and authenticate for GitHub with permission to create the requested repository (for example, gh auth login --hostname github.com). Install ru as well if you selected --ru. Apply checks required tools, authentication, and an existing repository name before creating the local project. An organization policy or a name claimed after preflight can still reject creation; the error is reported and the local project is retained.

Only the plan's publication files enter the initial commit. Private recovery state, Agent Mail connection settings, Beads runtime metadata, and unrelated files in the directory are excluded. Publication never force-pushes. --ru registers the repository in the matching private/public list; it does not run ru sync or change ru's projects directory or clone layout. In particular, a custom new-project path is not a new ru path mapping: later syncs follow your existing ru configuration. The plan captures the configuration and state directories from RU_CONFIG_DIR/RU_STATE_DIR, or their XDG/home defaults, so a changed environment cannot silently redirect registration at apply time.

If a later step fails, keep the saved plan and project:

acfs newproj --apply myapp-plan.json --yes --resume

The failure report identifies completed steps, whether the repository was created, and whether initial publication is confirmed or still unconfirmed. A push failure keeps the new repository available for retry; a registration failure keeps the published repository and retries ru registration. Resume reuses the recorded initial commit and checks the repository identity, visibility, local files, Git configuration, remote, and HEAD before continuing. It refuses changed or unrelated work instead of overwriting it. No repository or project files are deleted as rollback.

If creation may have succeeded but its immutable GitHub repository ID was not durably saved, automatic resume stops for manual review. It will not adopt a repository merely because the name matches. Inspect the reported GitHub destination and complete any remaining operations explicitly in that case. This workflow creates new repositories on GitHub.com; it does not attach existing repositories or configure GitHub Enterprise hosts.

Notes:

• The TUI uses gum when available (arrow keys, Space to toggle, Enter to confirm). Without gum, it falls back to numbered prompts.
• Minimum terminal size: 60x15.
• CLI mode skips existing AGENTS.md; the wizard overwrites it, so move it aside if you want to keep the old one.

acfs agents — Flywheel Agent Guide

ACFS generates a machine-wide agent guide (installed tools with live versions, workflows, safety rules). The guide lives only in ACFS-owned storage, and ACFS refreshes it there on install/update:

~/.acfs/docs/flywheel-agent-guide.md    # canonical, freely regenerated by ACFS
~/.acfs/docs/AGENTS.workspace.md        # workspace AGENTS.md template (canonical copy)

ACFS never automatically writes /AGENTS.md, ~/.codex/AGENTS.md, or a project's AGENTS.md — those files can contain user-authored rules and belong to you. (/data/projects/AGENTS.md is seeded once on a fresh install only when absent, and is never overwritten afterward.) Deploying the guide into a real instruction surface is an explicit step:

acfs agents update                       # regenerate the canonical guide
acfs agents path                         # print the canonical path
acfs agents install --codex-global       # deploy to ~/.codex/AGENTS.md (Codex global scope)
acfs agents install --project DIR        # deploy to DIR/AGENTS.md (project scope)
acfs agents install --workspace          # deploy to /data/projects/AGENTS.md
acfs agents install --root               # deploy to /AGENTS.md (legacy; not auto-discovered)
acfs agents install --to PATH            # deploy anywhere else

Deployment creates the destination only when it is absent, including when another process creates it during deployment. If the destination already exists with different content, the deploy refuses, leaves your file untouched, and writes a merge candidate next to it (<dest>.acfs-new) so you can diff and merge manually. An existing different candidate is preserved and a unique suffixed candidate is reported. Redeploying identical content is an idempotent no-op.

acfs agents update --output PATH uses the same create-only rules. Only the canonical guide in ACFS-owned storage is automatically replaced. Publication requires Python 3, rejects symlink destinations and parent directories, and stages complete content beside the destination before publishing it. Interrupted staging files are retained for inspection.

Discovery scopes worth knowing: Codex reads global guidance from ~/.codex/AGENTS.md and project guidance from the project root down to the working directory; filesystem-root /AGENTS.md is not automatically read by any major harness, which is exactly why ACFS no longer writes it.

Tool detection always runs in the target user's context (including under sudo, resolved via SUDO_USER with ~/.local/bin, ~/go/bin, etc. on PATH), so user-local tools are reported accurately.

acfs info — System Overview

Quickly displays installation and onboarding state without verification or live probes by default.

acfs info                # Terminal output (default)
acfs info --json         # JSON output for scripting
acfs info --html         # Self-contained HTML page
acfs info --minimal      # Just essentials (IP, key commands)
acfs info --live         # Include live coordination probes; can take longer

Example output:

╔══════════════════════════════════════════════════════════════╗
║                    ACFS System Info                           ║
╠══════════════════════════════════════════════════════════════╣
║  Host: vps-12345.contabo.net                                  ║
║  IP: 192.168.1.100                                            ║
║  User: ubuntu                                                 ║
║  Uptime: 3 days, 4 hours                                      ║
║                                                               ║
║  Quick Commands:                                              ║
║    cc    → Claude Code (dangerous mode)                       ║
║    cod   → Codex CLI (dangerous mode)                         ║
║    agy   → Antigravity CLI (Gemini 4 Argon High)              ║
║    ntm   → Named Tmux Manager                                 ║
╚══════════════════════════════════════════════════════════════╝

Design Philosophy:

• Speed: Reads local state without waiting for coordination probes; live telemetry is opt-in
• Read-only by default: Reads installation/onboarding state and local interfaces without invoking coordination tools or writing caches. Swarm values remain unknown until live telemetry is requested
• Live telemetry: --live probes the optional coordination tools, which may update their own local state. Dashboard generation requests this mode explicitly to populate its operations panel
• Offline by default: No network calls; IP discovery reads local interfaces and routing tables only
• Legacy IP cache: A cached value is reused only after a bounded read confirms a recent ordinary file and a valid IPv4 or IPv6 address. Linked, malformed, oversized or stale caches fall back to local discovery without changing the cache. If Python 3 is unavailable, local discovery still works
• Fallback: Graceful degradation if data missing

acfs cheatsheet — Alias Discovery

Parses ~/.acfs/zsh/acfs.zshrc to show all installed aliases and commands.

acfs cheatsheet              # List all aliases
acfs cheatsheet git          # Filter by category or search term
acfs cheatsheet --category Agents
acfs cheatsheet --search docker
acfs cheatsheet --json       # JSON output for tooling

Example output:

╔═══════════════════════════════════════════════════════════════╗
║  ACFS Cheatsheet                                               ║
╠═══════════════════════════════════════════════════════════════╣
║  Agents                                                        ║
║    cc   → claude --dangerously-skip-permissions                ║
║    cod  → codex --dangerously-bypass-approvals-and-sandbox     ║
║    agy  → agy --model 'Gemini 4 Argon (High)'                  ║
║                                                                ║
║  Git                                                           ║
║    gs   → git status                                           ║
║    gp   → git push                                             ║
║    gl   → git pull                                             ║
║    gco  → git checkout                                         ║
║                                                                ║
║  Modern CLI                                                    ║
║    ls   → lsd --inode --long --all                             ║
║    cat  → bat                                                  ║
║    grep → rg                                                   ║
║    lg   → lazygit                                              ║
╚═══════════════════════════════════════════════════════════════╝

acfs dashboard — HTML Status Page

Generates a self-contained HTML dashboard and optionally serves it.

acfs dashboard generate              # Generate ~/.acfs/dashboard/index.html
acfs dashboard generate --force      # Force regeneration
acfs dashboard serve                 # Serve on localhost:8080
acfs dashboard serve --port 3000     # Custom port
acfs dashboard serve --public        # Bind to 0.0.0.0

The default server accepts local connections. To view it from your laptop, use the SSH tunnel command printed at startup, then open http://localhost:8080. --public and a non-loopback --host expose the dashboard without authentication to anyone who can reach the port, including its hostnames and install state. Use an SSH tunnel on untrusted networks. The server publishes only index.html; temporary files, timestamps, other files, and directory listings are not served. The page and its parent directories must be real paths; linked paths are refused. Python 3 is required for generation and HTTP serving; you can also open an existing HTML page directly. Generation refuses linked or non-regular output files, including hardlinked freshness timestamps. It stages the complete page and timestamp in a private .staging directory before replacing them. Failed staging files are retained there for diagnosis; the error prints their location. Rendering has a 60-second limit. A valid recent page is reused without rewriting either file.

The dashboard provides:

• System health at a glance
• Tool versions and status
• Quick command reference
• Recent activity summary

acfs services — Background Daemon Management

Start, stop, restart, inspect, or follow logs for the local coordination daemons:

acfs services start
acfs services status
acfs services logs agent-mail
acfs services restart cass     # restart one service; the others keep running
acfs services drift            # is the live process on the installed binary?
acfs services stop

Agent Mail keeps its ACFS-reserved 127.0.0.1:8765 endpoint and reuses the native user service when one is already healthy. CM runs on 127.0.0.1:8766, and CM plus the CASS watch indexer run in the acfs-svc tmux session. start and status return nonzero if any daemon fails its runtime readiness check.

Lifecycle contract (the tmux tradeoff chosen in #196, made explicit per #360):

• The installer does not start this service group; run acfs services start yourself after install (and after every reboot).
• start is a one-shot launcher, not a foreground supervisor: it brings the daemons up, reports readiness, and exits.
• Only Agent Mail is normally boot-persistent, via its native systemd user service. CM and the CASS watch indexer live in the acfs-svc tmux session, which does not survive a reboot and does not restart crashed processes -- after a reboot or crash, rerun acfs services start.
• CM's HTTP server is optional if you only use cm context / cm reflect from the CLI; those read the store directly.
• Leaving the CASS watcher off can be deliberate (for example while diagnosing indexing or resource problems); acfs services status reporting it "not running" is not necessarily a fault.

Converging a partly-down group (#383): when the acfs-svc session already exists, start repairs it instead of reporting and exiting. It relaunches only the services that are not running -- a pane whose process is alive is never touched, which matters when the tmux server also hosts long-lived agent panes. acfs services repair is the same operation under its own name.

Preflight before teardown (#382): restart resolves and validates every binary it will need before it stops anything. Validation is the post-install smoke check from #378 -- the binary must exist, be executable, and answer a probe; a broken verdict (timeout, wrong architecture, missing loader, crash) aborts the restart with no service-state change, while an unsupported verdict (the CLI rejects --version/--help/version as unknown arguments) is accepted. Managed binaries are resolved from the ACFS install directories as well as PATH, so a noninteractive SSH shell without ~/.local/bin on PATH no longer takes the group down. restart also accepts service names (acfs services restart cass) to restart one service without interrupting the others.

Running-binary drift (#381): updating a tool replaces the file on disk, but a service keeps executing the inode it started with -- cass --version then reports the new release while the live watcher still runs the old code. ACFS compares what each service executes (/proc/<pid>/exe, which is not the same thing as what PATH resolves) against the installed binary, and warns with both paths and hashes from acfs services status, acfs doctor, and the end of acfs update. By default nothing is restarted automatically: the warning names the exact per-service restart command so you can pick a quiescent moment. To have acfs update restart chosen services when, and only when, this check finds them stale, list them in ACFS_UPDATE_RESTART_SERVICES (comma- or space-separated, e.g. cm or cm,cass; Dicklesworthstone/agentic_coding_flywheel_setup#464). Each restart is confirmed with the same check and reported; a listed name that is not a managed service is reported and ignored. To limit it to the nightly run, set it in a drop-in:

systemctl --user edit acfs-nightly-update.service
# [Service]
# Environment=ACFS_UPDATE_RESTART_SERVICES=cm

acfs services drift runs the check on demand (--robot for one service|state|detail line per service). The comparison needs procfs, so it reports unknown on platforms without one.

This lifecycle command is distinct from acfs services-setup, which configures credentials and integrations rather than background processes.

acfs services-setup — Credential Configuration

Interactive wizard for configuring AI agent credentials and cloud service logins.

acfs services-setup          # Run full setup wizard

Guides you through:

• Claude Code: API key configuration
• Codex CLI: ChatGPT account login
• Antigravity CLI: Google account authentication
• GitHub CLI: gh auth login
• Cloud CLIs: Wrangler, Supabase, Vercel authentication

Also offers to install DCG (Destructive Command Guard), a Claude Code hook that blocks destructive commands like rm -rf /.

acfs continue — Upgrade Progress

After an Ubuntu upgrade reboot, view installation progress:

acfs continue                # Show current upgrade status

Displays:

• Original Ubuntu version
• Target version
• Current upgrade stage
• Next steps after completion

Learning Hub (Web)

In addition to the terminal-based onboarding, ACFS provides a comprehensive web-based Learning Hub at agent-flywheel.com/learn.

Web Lessons

The Learning Hub provides interactive lessons with progress tracking:

These are the core lessons; the hub ships 65 lessons in total (the core track plus per-tool deep dives such as UBS, Agent Mail, CASS, Beads, SLB, RCH and the case studies below), all defined in apps/web/lib/lessons.ts.

Features:

• Progress tracking in localStorage
• Code blocks with copy buttons
• Expandable deep-dive sections
• Practical exercises

Command Reference

The Command Reference documents every installed tool:

Technical Glossary

The Glossary defines 100+ technical terms with:

• One-liner: Quick tooltip definition
• Full explanation: Plain language description
• Analogy: "Think of it like..."
• Why we use it: Problem it solves
• Related terms: For context

Example entry:

RAM (Random Access Memory)
├── Short: Fast temporary storage your computer uses while working
├── Long: RAM is your computer's short-term memory...
├── Analogy: Like your desk space while working
├── Why: More RAM = run more programs simultaneously
└── Related: vCPU, VPS, NVMe

Flywheel Visualization

The Flywheel page visualizes tool interactions:

Plan (Beads) ──> Coordinate (Agent Mail) ──> Execute (NTM + Agents)
      ^                                              │
      │                                              v
      └──── Remember (CASS Memory) <──── Scan (UBS) ┘

Workflow Scenarios:

The scenarios are defined in apps/web/lib/flywheel.ts; the page renders whatever that file contains.

Tool Catalog (TL;DR page)

The TL;DR page is the searchable catalog of installed tools (the old /tools page was folded into it and now redirects there):

• Search & Filter: A search box (press / to focus) filters tools by name, CLI command, or description
• Tool Details: Each card shows the tool's tagline, its CLI command as a chip, and a copyable example invocation
• Synergy Diagram: An interactive diagram shows how the flywheel tools feed each other
• Live Data: Cards are generated from acfs.manifest.yaml — manifest tools without a hand-curated entry are auto-appended so the page can never silently omit a tool

This page helps users discover tools they may not know about and understand how each fits into the agentic coding workflow.

Interactive Website Components

The wizard website includes specialized components for guiding beginners:

ConnectionCheck Component: A prominent visual that helps users verify they're connected to their VPS before running commands:

• Side-by-side comparison: "Wrong (laptop)" vs "Right (VPS)"
• Terminal prompt examples for Windows, Mac, and Linux
• Clear "STOP!" warning with color-coded styling

CommandCard Component: CLI instruction cards with:

• Syntax-highlighted code blocks
• One-click copy button
• Platform-specific variations (bash/zsh/PowerShell)
• Expandable explanations

Jargon Component (Responsive Technical Terms): A tooltip system (apps/web/components/jargon.tsx) that adapts to the pointer type:

Desktop behavior:

• Hover or keyboard focus reveals a floating definition card, rendered through a portal so it escapes stacking contexts
• Viewport-aware positioning (auto-flips when near edges)
• A short close delay so the pointer can travel into the card

Mobile behavior:

• Tap opens a bottom sheet (apps/web/components/ui/bottom-sheet.tsx, framer-motion) with the full definition
• Swipe-to-dismiss from the handle, Escape and backdrop dismissal, focus returned to the term
• Body scroll locked while open and restored on close

Visual features:

• Dotted primary-colored underline marks a term as interactive
• Reduced-motion users get fades instead of slides
• Colors come from the OKLCH design tokens

Content structure per term:

{
  term: "VPS",
  short: "Virtual Private Server - a remote computer you rent",
  long: "A VPS is your own slice of a powerful computer...",
  analogy: "Think of it like renting an apartment in a building",
  whyWeUseIt: "You get root access, dedicated resources...",
  relatedTerms: ["SSH", "Ubuntu", "RAM"]
}

Confetti Celebration: On lesson completion:

• Burst of celebratory confetti particles
• Randomized encouraging messages
• Special celebration for completing all lessons
• Respects prefers-reduced-motion setting

Stepper Component: Multi-step progress indicator:

• Visual step-by-step progress
• Clickable navigation
• Completion checkmarks
• Mobile-responsive design

Expanded Lesson Library

The Learning Hub includes specialized lessons for each tool in the Agent Flywheel stack:

Each lesson includes:

• Conceptual introduction
• Practical commands with examples
• Interactive exercises
• Common pitfalls to avoid
• Links to tool documentation

Interactive Onboarding (TUI)

After installation, users can learn the ACFS workflow through an interactive terminal-based tutorial. The onboarding TUI discovers lesson markdown files dynamically from acfs/onboard/lessons, so the curriculum can grow as new tools and workflows are added without changing the launcher.

Running Onboarding

onboard                # Launch interactive menu
onboard status         # Show completion status
onboard --list         # Alias for status
onboard 3              # Jump to lesson 3
onboard reset          # Reset progress and start fresh
onboard --reset        # Alias for reset

Lessons

Run onboard --help to see the currently discovered lesson list. The curriculum currently spans Linux basics, SSH, tmux, agent login, NTM, the flywheel workflow, updating, Beads, RCH, and other ACFS tools. Because lessons are discovered by filename, adding a new NN_name.md file automatically extends the tutorial.

Progress Tracking

Progress is saved in ~/.acfs/onboard_progress.json:

{
  "completed": [0, 1, 2],
  "current": 3,
  "started_at": "2024-12-20T10:30:00-05:00"
}

The TUI shows completion status for each lesson and suggests the next one to take. Users can jump to any lesson or re-take completed ones.

Enhanced UX with Gum

If Charmbracelet Gum is installed, the onboarding system uses it for enhanced terminal UI—selection menus, styled prompts, and better formatting. Without Gum, it falls back to simple numbered menus that work everywhere.

Tools Installed

ACFS installs a comprehensive suite of 30+ tools organized into categories:

Shell & Terminal UX

Languages & Package Managers

Dev Tools

Networking

Tailscale Integration:

Tailscale provides secure, encrypted networking between your devices without complex firewall configuration:

# Authenticate and join your tailnet
tailscale up

# Check connection status
tailscale status

# Get your Tailscale IP
tailscale ip

# SSH over Tailscale (bypasses firewalls)
ssh ubuntu@your-vps.tailnet-name.ts.net

Benefits for agentic workflows:

• Firewall-free access: Connect even when behind NAT or restrictive firewalls
• MagicDNS: Access your VPS by hostname instead of IP
• SSH keys over Tailscale: Use tailscale ssh for key-free authentication
• ACLs: Fine-grained access control for team environments

Compatible AI Coding Agents

ACFS ships 7 coding-agent modules; 3 of them install by default.

Turn any of them on or off at install time with the Module column above: --only <module> installs that agent plus its dependencies, --skip <module> leaves it out — for example --only agents.grok or --skip agents.codex. --list-modules prints every module id and --print-plan shows what a given selection would run.

What each one is for:

• Antigravity CLI — Google's successor to the Gemini CLI; ACFS pins its model and permissions via agy-locked.
• Claude Code — Long autonomous runs with deep tool use; the ACFS default driver.
• Codex CLI — Runs on a ChatGPT plan; --device-auth is the login path on a headless VPS.
• Grok CLI — xAI's terminal agent; also accepts GROK_DEPLOYMENT_KEY for headless use.
• oh-my-pi — Community fork of the Pi agent with its own model roster and credential broker.
• OpenCode — Multi-provider harness; drives Claude, GPT, and Gemini models from one TUI.
• Gemini CLI — Retired upstream on 2026-06-18; kept installable for existing setups, use Antigravity instead.

Vibe Mode Aliases:

# Claude Code with max memory (background tasks enabled by default)
alias cc='NODE_OPTIONS="--max-old-space-size=32768" claude --dangerously-skip-permissions'

# Codex with bypass and dangerous filesystem access
alias cod='codex --dangerously-bypass-approvals-and-sandbox --search -m gpt-6-astra -c model_reasoning_effort=xhigh -c model_reasoning_summary_format=experimental'

# Antigravity CLI, model/settings/DCG locked by the ACFS launcher
alias agy='$HOME/.local/bin/agy-locked'
alias gmi='$HOME/.local/bin/agy-locked'

Installation & Updates: Claude Code should be installed and updated using its native mechanisms:

• Install: ACFS uses the official native installer (claude.ai/install.sh), checksum-verified via checksums.yaml (installs to ~/.local/bin/claude)
• Update: Use claude update --channel latest (built-in) or run acfs update --agents-only

This ensures proper authentication handling and avoids issues with alternative package manager builds. ACFS updates Codex with Bun global package updates, Antigravity with its native agy update path, oh-my-pi with its native omp update path, and Grok CLI by re-running its checksum-verified installer.

Cloud & Database

Vault is installed by default (skip with --skip-vault). ACFS installs the Vault CLI so you have a real secrets tool available early; it does not automatically configure a Vault server for you.

Supabase networking note: some Supabase projects expose the direct Postgres host over IPv6-only (often on free tiers). If your VPS/network is IPv4-only, use the Supabase pooler connection string instead (or upgrade/configure networking for direct IPv4).

Agent Flywheel Stack (Core Tools)

The core suite of tools for professional agentic workflows:

Bundled Utilities

Additional productivity tools installed alongside the stack:

Doctor Command

acfs doctor performs comprehensive health checks on your installation:

$ acfs doctor

╔══════════════════════════════════════════════════════════════╗
║                    ACFS Health Check                          ║
╠══════════════════════════════════════════════════════════════╣
║ Identity                                                      ║
║   ✔ Running as ubuntu user                                    ║
║   ✔ Passwordless sudo enabled                                 ║
║                                                               ║
║ Workspace                                                     ║
║   ✔ /data/projects exists                                     ║
║                                                               ║
║ Shell                                                         ║
║   ✔ zsh installed                                             ║
║   ✔ oh-my-zsh installed                                       ║
║   ✔ powerlevel10k installed                                   ║
║   ✔ acfs.zshrc sourced                                        ║
║                                                               ║
║ Core Tools                                                    ║
║   ✔ bun 1.2.16                                                ║
║   ✔ uv 0.5.14                                                 ║
║   ✔ cargo 1.84.0                                              ║
║   ✔ go 1.23.4                                                 ║
║   ✔ ripgrep 14.1.0                                            ║
║   ✔ ast-grep 0.30.1                                           ║
║                                                               ║
║ Agents                                                        ║
║   ✔ claude 1.0.24                                             ║
║   ✔ codex 0.1.2504252326                                      ║
║   ✔ agy 1.0.12                                                ║
║                                                               ║
║ Cloud                                                         ║
║   ✔ vault 1.18.3                                              ║
║   ✔ wrangler 4.16.0                                           ║
║   ✔ supabase 2.23.4                                           ║
║   ✔ vercel 41.7.6                                             ║
║                                                               ║
║ Agent Flywheel Stack                                          ║
║   ✔ ntm 0.3.2                                                 ║
║   ✔ slb 0.2.1                                                 ║
║   ✔ ubs 0.1.8                                                 ║
║   ✔ bv 0.9.4                                                  ║
║   ✔ cass 0.4.2                                                ║
║   ✔ cm 0.1.3                                                  ║
║   ✔ caam 0.2.0                                                ║
║   ✔ dcg 0.1.0                                                 ║
║   ✔ ru 1.2.0                                                  ║
║   ⚠ mcp_agent_mail (not running)                              ║
║                                                               ║
║ Utilities                                                     ║
║   ✔ giil 3.0.0                                                ║
║   ✔ csctf 1.0.0                                               ║
╠══════════════════════════════════════════════════════════════╣
║ Overall: 35/36 checks passed                                  ║
╚══════════════════════════════════════════════════════════════╝

Generated Doctor Checks

Doctor checks are generated from the manifest (scripts/generated/doctor_checks.sh) to keep verification logic close to acfs.manifest.yaml. The acfs doctor command automatically sources these generated checks to verify all manifest-defined tools.

How it works:

1. The manifest generator creates doctor_checks.sh with verify commands for each module
2. acfs doctor sources this file and runs each verification check
3. Failed checks display a fix suggestion with the exact command to reinstall

Example output with fix suggestion:

  ✗ tools.lazygit - Lazygit terminal UI not found
    Fix: curl -fsSL https://agent-flywheel.com/install | bash -s -- --yes --force-reinstall --only tools.lazygit

This architecture ensures doctor checks stay in sync with the installer—if a tool is in the manifest, it will be verified.

Options

acfs doctor              # Interactive colorful output
acfs doctor --json       # Machine-readable JSON output
acfs doctor --quiet      # Exit code only (0=healthy, 1=issues)
acfs doctor --deep       # Run functional tests (auth, connections)
acfs doctor --fix        # Apply safe fixes for failed checks
acfs doctor --dry-run    # Preview fixes without applying
acfs doctor --no-cache   # Skip cache, run all checks fresh

Deep Checks (--deep)

The --deep flag runs functional tests beyond binary existence:

Deep checks use 15-second timeouts to avoid hanging on network issues. Successful results are cached for 5 minutes to speed up repeated runs.

Example output:

Deep Checks
  ✔ Claude auth configured
  ✔ PostgreSQL connection working
  ⚠ Codex not authenticated (run: codex login)
  ✔ GitHub CLI authenticated

8/9 functional tests passed in 3.2s

Auto-Fix Mode (--fix)

The --fix flag automatically applies safe, deterministic fixes for common issues:

acfs doctor --fix             # Apply safe fixes
acfs doctor --fix --dry-run   # Preview fixes without applying

Safe Auto-Fixers

These fixes are applied when --fix is used. Failed checks are fixed right away; warning-level checks (which most of these are) additionally need --yes, so the usual invocation is acfs doctor --fix --yes:

Safety Guarantees

• Never deletes user files — Only creates, modifies, or symlinks
• Backups before modify — SHA256-verified backups of all modified files
• Idempotent — Safe to run multiple times
• Logged — All changes recorded to ~/.local/share/acfs/doctor.log
• Reversible — Configuration-level fixes (PATH, sourcing, config copies, symlinks, plugin clones) record an undo command; tool installs are not auto-reverted

Example Dry-Run Output

DRY-RUN: acfs doctor --fix

Would apply the following fixes:

  [fix.path.ordering]
    Action: Prepend PATH directories to ~/.zshrc
    File: ~/.zshrc
    Backup: Yes (SHA256 verified)

  [fix.acfs.sourcing]
    Action: Add ACFS sourcing to .zshrc
    File: ~/.zshrc
    Backup: Yes (SHA256 verified)

Fixes that require manual action:
  [shell.ohmyzsh]
    Status: FAIL
    Suggestion: curl -fsSL https://install.ohmyz.sh/ | bash

Summary: 2 auto-fixes, 0 prompted, 1 manual

Manual-Only Fixes

Some operations are never auto-fixed and instead provide suggestions:

• Package manager operations (apt install ...)
• Anything requiring sudo
• File deletions
• Complex shell configuration changes

Undoing Changes

All changes made by --fix can be undone:

acfs undo --list      # List all changes
acfs undo chg_0001    # Undo specific change
acfs undo --all       # Undo all changes from the most recent fix session
acfs undo --everything  # Undo every recorded change across all sessions

Undo restores the whole-file backup taken just before the fix ran. Any edits you made to that file after the fix are reverted too, so copy them aside before undoing a fix to a file you have since changed. Tool installs performed by --fix record no automatic rollback; remove an unwanted tool manually.

The Wizard Website

The wizard guides beginners through a 13-step journey from "I have a laptop" to "AI agents are coding for me":

┌─────────────────────────────────────────────────────────────────────────────┐
│  ACFS Wizard                                                   [Step 3/13]  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │  STEP 3: Generate SSH Key                                              │ │
│  │  ──────────────────────────────────────────────────────────────────    │ │
│  │                                                                        │ │
│  │  Run this command in your terminal:                                    │ │
│  │                                                                        │ │
│  │  ┌─────────────────────────────────────────────────────────────────┐  │ │
│  │  │ ssh-keygen -t ed25519 -C "your-email@example.com"         [📋] │  │ │
│  │  └─────────────────────────────────────────────────────────────────┘  │ │
│  │                                                                        │ │
│  │  ☐ I ran this command                                                  │ │
│  │                                                                        │ │
│  │  [← Previous]                                        [Next Step →]     │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                             │
│  Progress: ●●●○○○○○○○○○○                                                   │
└─────────────────────────────────────────────────────────────────────────────┘

Wizard Steps

Key Features

• OS Detection: Auto-detects Mac vs Windows for tailored instructions
• Copy-to-Clipboard: One-click copy for all commands
• Handoff Runbook: Downloadable JSON/Markdown artifact for the installer command and recovery steps
• Progress Tracking: localStorage persistence across browser sessions
• Confirmation Checkboxes: "I ran this command" acknowledgments
• Troubleshooting: Expandable help for common issues

Local learning recommendations

The Learning Hub suggests up to three useful next steps from the lessons completed in your browser and your selected stack. Each suggestion explains its reason. The next guided lesson respects sequential access; tool references are always available. The goal selector can prioritize installation recovery or coordination with multiple agents. These choices and the recommendations do not prove that tools are installed or authenticated.

With a valid saved wizard target, the existing local doctor JSON reader appears on the hub. Use the recovery goal to reach setup guidance if no target is saved. Findings or coverage gaps prioritize a diagnostic action. Only an in-memory boolean reaches the recommender; report contents, private identifiers and raw fix commands are never persisted or sent to analytics. Clearing/replacing the report, changing installation context or leaving the page clears that signal. Recommendations do not run commands, mark lessons complete, change your stack selection or unlock gated lessons. Unknown selections prompt review; new users and completed courses retain useful reference links without requiring a backend.

Wizard Handoff Runbook

Step 9 can download a local handoff runbook in JSON or Markdown. The runbook is meant for the user and support loop when an SSH session drops, an install is interrupted, or the user needs to remember the exact command they ran.

Schema: acfs.handoff-runbook.v1

Host addresses are not written into the runbook. The installer command stays exact so a user can paste it back into the VPS session, and the artifact points to support-report.md and manifest.json for support-bundle review.

Technology Stack

Next.js 16 (App Router)
├── React 19
├── Tailwind CSS 4 (OKLCH colors)
├── shadcn/ui components
├── Radix UI primitives
└── Lucide icons

No backend required. All state is stored in:

• URL query parameters
• localStorage (agent-flywheel-user-os, agent-flywheel-vps-ip, agent-flywheel-wizard-completed-steps)

Wizard State Management

The wizard uses TanStack Query for state management with optimistic updates and cross-tab synchronization:

Architecture:

// Query-based state with localStorage persistence
const { data: steps } = useQuery({
  queryKey: ['wizardSteps', 'completed'],
  queryFn: getCompletedSteps,  // Reads from localStorage
  staleTime: 0,                // Always check for updates
  gcTime: Infinity,            // Never garbage collect
});

Optimistic Updates with Rollback:

const mutation = useMutation({
  mutationFn: async (stepId) => {
    const newSteps = addCompletedStep(currentSteps, stepId);
    setCompletedSteps(newSteps);  // Persist to localStorage
    return newSteps;
  },
  onMutate: (stepId) => {
    // Optimistically update cache immediately
    const previousSteps = queryClient.getQueryData(queryKey);
    queryClient.setQueryData(queryKey, addCompletedStep(baseSteps, stepId));
    return { previousSteps };  // For rollback
  },
  onError: (_err, _stepId, context) => {
    // Rollback on failure
    queryClient.setQueryData(queryKey, context.previousSteps);
  },
});

Cross-Tab Synchronization: The wizard maintains sync across browser tabs via two mechanisms:

1. Custom DOM events for same-tab coordination between components
2. Storage events for cross-tab updates when localStorage changes

// Same-tab: custom event dispatch
window.dispatchEvent(new CustomEvent('acfs:wizard:completed-steps-changed', {
  detail: { steps }
}));

// Cross-tab: storage event listener
window.addEventListener('storage', (event) => {
  if (event.key === COMPLETED_STEPS_KEY) {
    queryClient.setQueryData(queryKey, getCompletedSteps());
  }
});

Safe localStorage Utilities: All localStorage access is wrapped in safe utilities that handle SSR, private browsing, and quota exceeded errors:

// Safe read (returns null on any error)
export function safeGetJSON<T>(key: string): T | null;

// Safe write (returns boolean success)
export function safeSetJSON(key: string, value: unknown): boolean;

// URL preservation for state fallback
export function withCurrentSearch(path: string): string;

This architecture ensures the wizard progress survives browser refreshes, works across tabs, and degrades gracefully when localStorage is unavailable.

Configuration Files

ACFS deploys optimized configuration files to ~/.acfs/ on the target VPS.

~/.acfs/zsh/acfs.zshrc

A comprehensive zsh configuration that's sourced by ~/.zshrc:

Prompt resource limits on swarm hosts:

ACFS defaults GITSTATUS_NUM_THREADS to 2 worker threads before loading Powerlevel10k. This bounds each new prompt daemon's worker pool on hosts with many tmux panes. A normal interactive terminal retains its Git prompt; each pane can still have its own daemon. An explicit nonempty value is preserved:

# In ~/.zshrc, before sourcing the ACFS configuration:
GITSTATUS_NUM_THREADS=4
source "$HOME/.acfs/zsh/acfs.zshrc"

Prompt themes are initialized only for interactive terminal sessions with TTY input and output. Command-mode shells such as zsh -lic 'command', including those running in a PTY, skip Powerlevel10k and the fallback Starship prompt. The agent markers CODEX_REMOTE_PAYLOAD, SIFS_AGENT, and AGENT_ENV also suppress theme initialization when nonempty. The existing VS Code plain prompt is selected before any heavy theme starts. Paths, aliases, and ACFS commands remain available in these shells.

The thread setting applies when a daemon starts. Open a new shell or tmux pane after updating; ACFS does not terminate existing prompt daemons. A user theme loaded separately before ACFS remains under that user's control.

Oh-My-Zsh Plugins (14 total):

Note: zsh-autosuggestions and zsh-syntax-highlighting are custom plugins installed from GitHub. They must be listed last for optimal performance.

Path Configuration:

export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"
export PATH="$HOME/go/bin:$PATH"
export PATH="$HOME/.bun/bin:$PATH"

Atuin is still installed, but ACFS keeps it behind the guarded ~/.local/bin/atuin shim instead of putting ~/.atuin/bin at the front of interactive shell PATH.

Modern CLI Aliases:

alias ls='lsd --inode --long --all'
alias ll='lsd -l'
alias tree='lsd --tree'
alias cat='bat'
alias grep='rg'
alias vim='nvim'
alias lg='lazygit'

Tool Integrations:

# Zoxide (smarter cd)
eval "$(zoxide init zsh)"

# direnv (directory env vars)
eval "$(direnv hook zsh)"

# fzf (fuzzy finder)
source /usr/share/doc/fzf/examples/key-bindings.zsh

Shell Keybindings (Quality of Life):

Atuin History Bindings: ACFS intentionally does not enable Atuin's zsh preexec/precmd integration by default. Atuin's searchable CLI remains available as atuin search, but the automatic shell hook can record every coding-agent command and grow the Atuin database fast enough to make shells laggy.

~/.acfs/tmux/tmux.conf

A tmux configuration specifically optimized for NTM and multi-agent workflows:

Key Bindings:

Prefix: Ctrl+a (not Ctrl+b - more ergonomic)
Split horizontal: |  (preserves working directory)
Split vertical: -    (preserves working directory)
Navigate panes: h/j/k/l (vim-style)
Resize panes: H/J/K/L (repeatable with -r flag)
Reload config: r
New window: c (preserves working directory)

Copy Mode (vim-style):

Enter copy mode: prefix + [
Begin selection: v
Rectangle selection: r
Copy and exit: y

Agent Workflow Optimizations:

Catppuccin-Inspired Theme:

# Status bar (top position, less intrusive)
status-style: bg=#1e1e2e, fg=#cdd6f4

# Session indicator (blue accent)
status-left: #[fg=#89b4fa,bold] #S

# Active window highlight (pink accent)
window-status-current-format: #[fg=#f5c2e7,bold] #I:#W

# Pane borders
pane-border-style: fg=#313244
pane-active-border-style: fg=#89b4fa  # Blue highlight

Local Overrides: The config sources ~/.tmux.conf.local if it exists, allowing personal customizations without modifying ACFS defaults.

Library Modules

The installer is organized into modular Bash libraries in scripts/lib/:

logging.sh

Colored console output utilities:

log_step "1/8" "Installing packages..."  # Blue step indicator
log_detail "Installing zsh..."           # Gray indented detail
log_success "Complete"                    # Green checkmark
log_warn "May take a while"              # Yellow warning
log_error "Failed"                        # Red error
log_fatal "Cannot continue"              # Red error + exit 1

security.sh

HTTPS enforcement and checksum verification:

enforce_https "$url"                     # Fail if not HTTPS
verify_checksum "$url" "$sha256" "$name" # Verify before execute
fetch_and_run "$url" "$sha256" "$name"   # Verify + execute in one

os_detect.sh

OS detection and validation:

detect_os()      # Sets OS_ID, OS_VERSION, OS_CODENAME
validate_os()    # Checks supported Ubuntu or Arch-family releases
is_fresh_vps()   # Heuristic detection of fresh VPS
get_arch()       # Returns amd64/arm64
is_wsl()         # Detects WSL
is_docker()      # Detects Docker container

user.sh

User account normalization:

ensure_user()              # Creates ubuntu user if missing
enable_passwordless_sudo() # Adds NOPASSWD to sudoers
migrate_ssh_keys()         # Copies keys from root to ubuntu
normalize_user()           # Full normalization sequence

update.sh

Component update logic with version tracking and logging:

update_apt()       # apt update/upgrade with lock detection
update_bun()       # bun upgrade with version tracking
update_agents()    # Claude, Codex, Antigravity, omp, Grok (version before/after)
update_cloud()     # Wrangler, Supabase, Vercel (Supabase uses verified release tarball)
update_rust()      # rustup update stable
update_uv()        # uv self update
update_go()        # Go toolchain update
update_shell()     # OMZ, P10K, plugins, Atuin, Zoxide
update_stack()     # Agent Flywheel stack tools

# Features:
# - Automatic logging to ~/.acfs/logs/updates/
# - Version tracking (before/after for each tool)
# - APT lock detection and warning
# - Reboot-required detection for kernel updates
# - Dry-run mode with --dry-run flag

gum_ui.sh

Enhanced terminal UI using Charmbracelet Gum:

print_banner()           # ASCII art ACFS banner
gum_step/gum_detail      # Styled output
gum_success/warn/error   # Colored messages
gum_spin                 # Spinner for long operations
gum_confirm              # Yes/No prompt
gum_choose               # Selection menu

Falls back to basic echo if Gum is not installed.

error_tracking.sh

Sophisticated error collection and reporting:

track_error "phase" "step" "error_message"
track_warning "phase" "step" "warning_message"
get_error_report                    # Generate structured error report
get_error_count                     # Count of tracked errors
has_errors                          # Boolean check for any errors

Features:

• Collects errors without aborting execution
• Associates errors with phase and step context
• Generates end-of-run summary reports
• Distinguishes warnings from errors

state.sh

State machine management for installation progress (v3 schema):

state_init                          # Initialize state file
state_get_phase                     # Current phase
state_set_phase "phase_name"        # Set current phase
state_mark_complete "phase_name"    # Mark phase complete
state_has_completed "phase_name"    # Check if phase done
state_save                          # Persist to disk (atomic)
state_load                          # Load from disk

The state file (~/.acfs/state.json) uses atomic writes to prevent corruption.

contract.sh

Runtime contract validation for generated scripts:

acfs_require_contract "module:${module_id}"  # Assert module environment is ready
acfs_check_contract                 # Non-fatal contract check

Validates that required environment variables and functions exist before execution:

• TARGET_USER, TARGET_HOME, MODE
• ACFS_BOOTSTRAP_DIR, ACFS_LIB_DIR
• Logging functions: log_detail, log_success, etc.

smoke_test.sh

Standalone post-install verification. The installer itself runs its own inline run_smoke_test (8 critical checks, defined in install.sh) at the end of an install; scripts/lib/smoke_test.sh is the larger, separately tested version of the same checks and is not invoked by the installer:

run_smoke_test                      # Execute all smoke tests

Critical Checks (must pass):

• Running as ubuntu user
• Passwordless sudo enabled
• Zsh is default shell
• Core tools accessible (bun, uv, cargo)

Non-Critical Checks (warnings only):

• Agent authentication configured
• Cloud CLIs authenticated
• Optional tools installed

Example output:

[Smoke Test]
  ✅ Running as ubuntu user
  ✅ Passwordless sudo enabled
  ✅ Zsh is default shell
  ✅ bun --version works
  ⚠️  Codex not authenticated (run: codex login)
  ✅ 8/9 checks passed

session.sh

Agent session export functionality for sharing and replay:

session_export "claude-code" "session_id" "/output/path"
session_list                        # List exportable sessions
session_validate "/export/file.json"

Implements the Session Export Schema for cross-agent sharing:

interface SessionExport {
  schema_version: 1;
  exported_at: string;              // ISO8601
  session_id: string;
  agent: "claude-code" | "codex" | "agy";
  model: string;
  summary: string;
  duration_minutes: number;
  stats: {
    turns: number;
    files_created: number;
    files_modified: number;
    commands_run: number;
  };
  outcomes: Array<{
    type: "file_created" | "file_modified" | "command_run";
    path?: string;
    description: string;
  }>;
  key_prompts: string[];            // Notable prompts for learning
  sanitized_transcript: Array<{
    role: "user" | "assistant";
    content: string;
    timestamp: string;
  }>;
}

tailscale.sh

Zero-config VPN setup for secure remote access:

install_tailscale                   # Install via official APT repo
verify_tailscale                    # Check installation
tailscale_status                    # Get connection status

Tailscale provides:

• Secure mesh networking between your devices
• SSH over Tailscale for firewall-free access
• MagicDNS for hostname-based addressing
• ACL-based access control

After installation, run tailscale up to authenticate and join your tailnet.

ubuntu_upgrade.sh

Multi-reboot Ubuntu version upgrade automation, invoked only when an upgrade is explicitly requested:

start_ubuntu_upgrade                # Begin upgrade chain
check_upgrade_status                # Current upgrade state
resume_upgrade_after_reboot         # Continue after reboot

Handles the complex multi-step Ubuntu upgrade process:

1. Detects current version
2. Calculates a supported LTS upgrade path (e.g., 24.04 → 26.04)
3. Performs sequential do-release-upgrade operations
4. Installs systemd service for post-reboot resume
5. Continues ACFS installation after reaching target

MCP Agent Mail Integration

ACFS includes integration with MCP Agent Mail for multi-agent coordination:

What Agent Mail Provides

• Identities: Each agent registers with a unique name
• Inbox/Outbox: Message-based communication between agents
• File Reservations: Advisory leases to prevent agents from clobbering each other's work
• Searchable Threads: Full-text search across all messages
• Git Persistence: All artifacts stored in git for human auditability

Port 8765 is reserved for Agent Mail

ACFS runs Agent Mail as a user service bound to 127.0.0.1:8765 and health-checks it there. cm serve (CASS Memory's MCP HTTP server) defaults to the same address, so on an ACFS machine start it on another port (cm serve --port 8766, or MCP_HTTP_PORT=8766 cm serve); otherwise whichever process starts second fails to bind and MCP clients can end up talking to the wrong server. If Agent Mail cannot start, the installer reports which process is holding the port.

Core Patterns

1. Register Identity:

# In your agent, call:
mcp.ensure_project(project_key="/data/projects/my-project")
mcp.register_agent(project_key=..., program="claude-code", model="opus-4.5")

2. Reserve Files Before Editing:

mcp.file_reservation_paths(
    project_key=...,
    agent_name="BlueLake",
    paths=["src/**"],
    ttl_seconds=3600,
    exclusive=true
)

3. Communicate:

mcp.send_message(
    project_key=...,
    sender_name="BlueLake",
    to=["GreenCastle"],
    subject="Review needed",
    body_md="Please review the auth changes..."
)

Macros for Speed

When speed matters more than fine-grained control:

mcp.macro_start_session(...)      # Ensure project + register + fetch inbox
mcp.macro_prepare_thread(...)     # Align with existing thread
mcp.macro_file_reservation_cycle(...)  # Reserve + work + release
mcp.macro_contact_handshake(...)  # Request contact permissions

Destructive Command Guard (dcg)

dcg is a high-performance Claude Code hook that blocks dangerous git and filesystem commands before they execute. Built in Rust for sub-millisecond latency, it provides mechanical enforcement of safety rules that instructions alone cannot guarantee.

Why dcg Exists

On December 17, 2025, an AI agent ran git checkout -- on files containing hours of uncommitted work from a parallel coding session. The files were recovered via git fsck --lost-found, but the incident made one thing clear: instructions in AGENTS.md don't prevent execution. dcg provides mechanical enforcement.

What Gets Blocked

What Gets Allowed

Safe variants are allowlisted:

• git checkout -b <branch> — Creates branch, doesn't touch files
• git restore --staged — Only unstages, doesn't discard
• git clean -n — Dry-run preview
• Temp directory cleanup still requires explicit human approval when an agent would delete files

Installation

acfs update --stack-only

Claude Code Configuration

Add to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "dcg"}]
      }
    ]
  }
}

Modular Pack System

dcg uses a modular pack system for extensibility. Enable additional packs in ~/.config/dcg/config.toml:

[packs]
enabled = [
    "database.postgresql",
    "containers.docker",
    "kubernetes",
]

Available packs: database.*, containers.*, kubernetes.*, cloud.*, infrastructure.*, system.*, package_managers.

Repo Updater (ru)

ru is a production-grade CLI tool for synchronizing collections of GitHub repositories and automating commit workflows across dirty repos with AI assistance.

Core Features

• Multi-repo sync: Clone missing repos, pull updates, detect conflicts
• Commit sweep: groups uncommitted changes across repositories into logical conventional commits (plan first, --execute to apply)
• AI code review: Orchestrate Claude Code review sessions for open issues/PRs
• Work-stealing queue: Parallel execution with load-balanced workers
• NTM integration: Session management via Named Tmux Manager

Quick Start

{ curl -fsSL "https://cdn.jsdelivr.net/gh/Dicklesworthstone/repo_updater@main/install.sh" || curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/repo_updater/main/install.sh"; } | bash

Initialize configuration:

# Initialize configuration
ru init --example

# Sync all repositories
ru sync

# Check status without changes
ru status

Commit Sweep Workflow

The commit-sweep command groups the changes in your dirty worktrees into logical conventional commits:

# Preview the commit plan (dry run is the default)
ru commit-sweep

# Execute the planned commits
ru commit-sweep --execute

# Keep manually staged files as their own group; limit to matching repos
ru commit-sweep --respect-staging --repos='*_rust' --execute

Two-Step Workflow:

1. Plan: Inspects every dirty worktree and prints the commits it would make
2. Execute: With --execute, makes those commits with deterministic git commands (never pushes)

Configuration

# ~/.config/ru/config
PROJECTS_DIR=/data/projects
LAYOUT=flat                   # flat|owner-repo|full
UPDATE_STRATEGY=ff-only       # ff-only|rebase|merge
PARALLEL=4

Repo list format (~/.config/ru/repos.d/public.txt):

owner/repo
owner/repo@develop            # Pin to branch
owner/repo as custom-name     # Custom directory name

Get Image from Internet Link (giil)

giil downloads full-resolution images from cloud photo shares to your terminal. Essential for remote debugging workflows where you need to analyze screenshots in SSH sessions.

Supported Platforms

Usage

# Basic download
giil "https://share.icloud.com/photos/02cD9okNHvVd-uuDnPCH3ZEEA"
# Output: /current/dir/icloud_20240115_143245.jpg

# Download to specific directory
giil "..." --output ~/Downloads

# Get JSON metadata
giil "..." --json

# Download all photos from album
giil "..." --all --output ~/album

Installation

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/giil/main/install.sh?v=3.0.0" | bash

Visual Debugging Workflow

1. Screenshot UI bug on iPhone
2. Wait for iCloud sync to Mac
3. Share via Photos.app → Copy iCloud Link
4. Paste link into remote terminal running Claude Code
5. giil fetches the image locally
6. AI assistant analyzes the screenshot

Chat Shared Conversation to File (csctf)

csctf converts public AI conversation share links into clean, searchable Markdown and HTML transcripts. Perfect for archiving AI conversations, building knowledge bases, and sharing with teams.

Supported Providers

Usage

# Basic conversion
csctf https://chatgpt.com/share/69343092-91ac-800b-996c-7552461b9b70
# Creates: <slug>.md and <slug>.html

# Markdown only
csctf "..." --md-only

# Publish to GitHub Pages
csctf "..." --publish-to-gh-pages --yes

# JSON metadata output
csctf "..." --json

Installation

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/chat_shared_conversation_to_file/main/install.sh | bash

Output Features

• Markdown: Clean formatting with preserved code blocks and language hints
• HTML: Zero-JavaScript static page with syntax highlighting
• Deterministic filenames: <slug>_YYYYMMDD.md for reliable archival
• Collision handling: Auto-increments suffix to avoid overwrites

CI/CD

ACFS does not use GitHub Actions: every workflow under .github/workflows/ is disabled, and the checks below run locally or on the maintainer's own machines (scripts/release-doctor.sh, scripts/checksum-monitor-local.sh on a systemd timer, the Docker and QEMU factory harnesses, and dsr for releases). The workflow descriptions that follow document what each disabled workflow used to do and what replaced it.

Installer Testing (installer.yml)

# Runs on every push and PR
jobs:
  shellcheck:
    - Lints all bash scripts with ShellCheck

  integration:
    - Matrix tests across Ubuntu 24.04, 25.04, 25.10
    - Runs full installation in Docker
    - Verifies all tools installed correctly
    - Runs acfs doctor to confirm health

  factory-e2e:
    - Runs the literal public curl|bash installer on QEMU/KVM or a fresh real Ubuntu host
    - Requires systemd, SSH, and a disposable factory VM/VPS semantics
    - Verifies ubuntu user creation, SSH key merge, user services, tool health, and idempotency

Docker catches shell and package regressions early. The factory E2E is the authoritative release gate for the real beginner VPS path because it exercises systemd, SSH, login/user-service behavior, and provider image defaults that containers cannot model. A Docker pass is not sufficient release proof by itself.

Local Release Doctor (scripts/release-doctor.sh)

Run the local release gate before tagging or publishing a release candidate:

bash scripts/release-doctor.sh --full --network=check
bash scripts/release-doctor.sh --json --full --network=check > release-doctor.json

For a fast local readiness check while developing:

bash scripts/release-doctor.sh --json

The release doctor composes the maintainer checks that are easy to forget:

• branch policy and clean worktree status
• shellcheck install.sh scripts/**/*.sh
• manifest/generated/checksum drift via scripts/check-manifest-drift.sh --json --quiet
• verified-installer checksum candidate review with --network=check
• website type-check, lint, and production build when apps/web changed or --full is set

The checksum candidate check uses the canonical updater output. If the generated body differs from checksums.yaml, review the diff before release; if only the timestamp header differs, leave checksums.yaml unchanged. The default --network=skip keeps routine runs offline, and --web=auto runs website checks only when web files changed unless --full or --web=always is provided.

Stack Provenance Report (scripts/stack-provenance-report.sh)

Use the stack provenance report when reviewing Agent Flywheel stack tool freshness before release:

bash scripts/stack-provenance-report.sh --json
bash scripts/stack-provenance-report.sh --network=check --json

Offline mode reports local manifest/checksum consistency for stack tools. Network mode also checks GitHub latest release metadata and generates a checksum candidate without writing checksums.yaml. Changed stack installer hashes fail the report, unrelated checksum diffs are called out separately, and rch release changes are flagged as mandatory checksum-refresh review items.

Network mode also records, per tool, which Linux architectures the latest release ships a build for (architecture.linux). A release with an x86_64 Linux build but no aarch64 one is a warning, because ARM64 installs then compile from source or fail. As of 2026-10-09, rch is the only such stack tool (upstream issue remote_compilation_helper#96).

Agent Readiness Audit (scripts/agent-readiness-audit.sh)

Run the local agent readiness audit before launching a swarm on a freshly installed VPS (the installer ships it; from a checkout, bash scripts/agent-readiness-audit.sh is equivalent):

acfs agent-readiness
acfs agent-readiness --json
acfs agent-readiness --rehearse --profile claude:work --profile codex:main        # plan only
acfs agent-readiness --rehearse --profile claude:work --profile codex:main --run  # run local CAAM status/--version checks

Rehearsal uses isolated profiles from caam profile ls, never activates, logs in or rotates accounts, and only proves local startup, not live authentication (see acfs agent-readiness --rehearse --help for the opt-in live check).

The audit checks Claude Code, Codex CLI, Antigravity CLI, and caam without printing token values or auth file contents. It reports CLI presence, version availability, parseable auth/config files, CAAM default profile consistency, and stale CAAM defaults that point at missing profiles.

Useful options:

acfs agent-readiness --no-version  # Skip CLI --version probes
acfs agent-readiness --home /home/ubuntu --path "$PATH"

Treat failures as launch blockers. Warnings usually mean the CLI is installed but needs a user sign-in or CAAM default profile selection.

Website Deployment (website.yml)

# Builds and deploys the Next.js wizard
jobs:
  build:
    - Type-check TypeScript
    - Run ESLint
    - Build production bundle

  deploy:
    - Deploy to Vercel (production)

Automated Checksum + Drift Repair (scripts/checksum-monitor-local.sh)

ACFS checks upstream installer changes from a local systemd timer (every 15 minutes, in a dedicated clone on a maintainer box). The retired GitHub Actions monitor is kept for reference; it is not the publication path.

scripts/checksum-monitor-local.sh      # the monitor
scripts/templates/acfs-checksum-monitor.* # timer + service templates

How It Works:

1. Bind a clean base: Requires a clean main checkout matching both remote compatibility refs. Installs manifest dependencies with --frozen-lockfile --ignore-scripts and checks generated artifacts with scripts/check-manifest-drift.sh --json. Existing drift stops the run and must be repaired separately.
2. Observe the complete installer set: Downloads every required installer and binds its URL and SHA256 to the exact existing checksums.yaml. Any fetch error, skipped entry, malformed report, or repository change stops publication.
3. Select prior authorization: For changed URLs outside the canonical https://raw.githubusercontent.com/Dicklesworthstone/ owner path, records review evidence in a GitHub issue. A human must review the upstream bytes and authorize either the complete external digest with authorize:<digest> or an explicitly reviewed subset using the command below. Digests bind external tool names, URLs, expected pins and observed hashes; unrelated commits and trusted changes do not invalidate them. The authorization file must be owner-only, regular, single-link, and non-symlink. A missing, malformed, stale, or unsafe record grants no external authority.
4. Build and validate offline: Uses the complete first observation to construct the candidate, without downloading installers a second time. Selects trusted-owner mismatches and exactly the authorized external tools; every deferred external pin stays unchanged. The validator checks the exact selected mismatch set, unchanged URLs and unchanged unselected pins. Its default, without explicit selection, still requires all observed mismatches. A changing external endpoint therefore cannot invalidate trusted publication through a second fetch. If issue delivery fails, the bound evidence stays in local state with a warning; approved external changes still require recorded review before mutation.
5. Generate and publish: Places the validated candidate, regenerates its installer ledger and web metadata, checks the complete generated contract, and commits only the declared publication paths. Rechecks retained evidence and selected authorization after remote probes, immediately before commit and push, and before accepting remote readback. Pushes both compatibility refs atomically and reads them back before recording the result. Pending external review reports result=deferred state=DEFERRED, including after an approved subset publishes, and leaves the deferred review open. An accepted run with no pending review records HEALTHY. Authorization is consumed only after accepted external publication.