{"id":51727431,"url":"https://github.com/fidpa/claude-code-live-usb","last_synced_at":"2026-07-17T21:40:17.945Z","repository":{"id":360790895,"uuid":"1251717955","full_name":"fidpa/claude-code-live-usb","owner":"fidpa","description":"Bring an AI CLI onto an Ubuntu Live-USB as a JA-gated lead operator for bare-metal maintenance (LVM, MD-RAID, recovery).","archived":false,"fork":false,"pushed_at":"2026-05-27T21:27:52.000Z","size":76,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-17T21:39:56.088Z","etag":null,"topics":["ai-tools","bare-metal","bash","devops","linux","live-usb","lvm","mdadm","recovery","sre","sysadmin","ubuntu"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fidpa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-27T21:11:01.000Z","updated_at":"2026-05-27T21:27:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fidpa/claude-code-live-usb","commit_stats":null,"previous_names":["fidpa/claude-code-live-usb"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/fidpa/claude-code-live-usb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidpa%2Fclaude-code-live-usb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidpa%2Fclaude-code-live-usb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidpa%2Fclaude-code-live-usb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidpa%2Fclaude-code-live-usb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fidpa","download_url":"https://codeload.github.com/fidpa/claude-code-live-usb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidpa%2Fclaude-code-live-usb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35597010,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-17T02:00:06.162Z","response_time":116,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","bare-metal","bash","devops","linux","live-usb","lvm","mdadm","recovery","sre","sysadmin","ubuntu"],"created_at":"2026-07-17T21:40:17.200Z","updated_at":"2026-07-17T21:40:17.939Z","avatar_url":"https://github.com/fidpa.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code on a Live-USB\n\n![CI](https://github.com/fidpa/claude-code-live-usb/actions/workflows/lint.yml/badge.svg)\n![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)\n![Platform](https://img.shields.io/badge/Platform-Linux-blue?logo=linux)\n![Ubuntu](https://img.shields.io/badge/Ubuntu-22.04%20%7C%2024.04-orange?logo=ubuntu)\n![Bash](https://img.shields.io/badge/Bash-4.0%2B-blue?logo=gnubash)\n![Status](https://img.shields.io/badge/status-beta-yellow.svg)\n\n**Bring an AI CLI onto the Ubuntu Live-USB you booted from, as a JA-gated lead operator for bare-metal maintenance.**\n\n\u003e Boot a vanilla Ubuntu Live-USB. Run one bootstrap script. Now an AI coding\n\u003e agent is sitting at the same terminal as you, has read your project's\n\u003e documentation, and is ready to talk you through a bare-metal maintenance\n\u003e operation.\n\n## The Problem\n\nBare-metal Linux maintenance is exactly the kind of work where you want a\nsecond set of eyes: shrinking an LVM volume, replacing a failed disk,\nrecovering from a broken initramfs, renewing a certificate that lives\ninside a recovery image. But it is also the work where you cannot have\nthose eyes. The machine is in single-user mode, the network is unreliable,\nthe clock is wrong, and your normal tools (browser, IDE, ChatGPT tab) are\non a different continent of your filesystem.\n\nThe standard answer is \"print the runbook and pray\". This project's answer\nis: bring the AI with you, on the same USB stick you booted from.\n\n## What You Get\n\nA ~488 MB usable ext4 partition (carved from a `+512M` sgdisk slot; ext4\noverhead and root-reserved blocks account for the difference) on your\nexisting Live-USB containing:\n\n- The AI CLI binary, ready to run as `root` after the bootstrap.\n- A 5-script payload on the stick (`find-stick`, `cc-setup`,\n  `mount-target`, `pre-resize-snapshot`, `start-claude`) plus one\n  stick-builder (`build-stick`) that runs on your workstation. The\n  case study adds a 7th script (`shrink-lv-extend-other`) as a worked\n  maintenance example.\n- A \"briefing\" pattern that lets the AI act as the **lead operator** for\n  a runbook. You answer `JA`/`NEIN`, it does the orchestration.\n- A worked example (LVM shrink/grow under MD-RAID) with the operations\n  report from the first real-world run, including the three corrections\n  it took to get right.\n\n## Requirements\n\n| Component | Needed for | Notes |\n|---|---|---|\n| Ubuntu Live-USB | always | Desktop ISO recommended (GNOME auto-mount); Server ISO works with manual mounting |\n| AI CLI binary (x86-64) | always | You supply it, see [`2-stick-payload/bin/README.md`](2-stick-payload/bin/README.md). ARM hosts need an ARM build. |\n| Free space on the stick | always | ~512 MB beyond the ISO partition; a 16 GB+ stick is comfortable |\n| `mdadm`, `lvm2`, `e2fsprogs` | MD-RAID / LVM targets | installed into the live session, not bundled in the Desktop ISO |\n| Bash | always | 4.0+, present on any current Ubuntu |\n\n## Quick Start (operator view)\n\nYou have already booted the Live-USB. You are at a terminal as `root`.\n\n```bash\nSTICK=$(/media/ubuntu/CC-TOOLS/find-stick.sh)\n\nbash $STICK/cc-setup.sh\nDEBIAN_FRONTEND=noninteractive apt-get install -y mdadm lvm2 e2fsprogs\nbash $STICK/mount-target.sh\nbash $STICK/start-claude.sh\n```\n\nThat is the entire memorised sequence. After `start-claude.sh` the AI session\ntakes over: it reads `CLAUDE.md` and `.claude/*` from your repository, reads\nthe runbook in `docs/runbooks/...`, and starts asking the questions a careful\noperator would ask (*\"Is the database VM shut down? Are you sure the disk\nserial number matches the one in the runbook?\"*).\n\n## How It Works (architecture in one screen)\n\n```\n  ┌────────────────────────────────────────────────────────────────┐\n  │  Vanilla Ubuntu Desktop Live-USB                               │\n  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │\n  │  │ sdX1 iso9660 │  │ sdX2 vfat ESP│  │ sdX4 ext4 \"CC-TOOLS\" │  │\n  │  │ (Ubuntu ISO) │  │ (boot)       │  │  this project        │  │\n  │  └──────────────┘  └──────────────┘  └──────────┬───────────┘  │\n  │                                                  │              │\n  │  /media/ubuntu/CC-TOOLS/  ← GNOME automount      │              │\n  │      ├─ find-stick.sh   ← memorize one path      │              │\n  │      ├─ cc-setup.sh     ← installs AI + creds    │              │\n  │      ├─ mount-target.sh ← mdadm/vgchange/mount   │              │\n  │      ├─ start-claude.sh ← shows briefing, runs   │              │\n  │      └─ bin/\u003cai-binary\u003e                          │              │\n  └────────────────────────────────────────────────────────────────┘\n                                                     │\n                                                     ▼\n  ┌────────────────────────────────────────────────────────────────┐\n  │  Target machine's NVMe (read-only mounted at /mnt/target-root) │\n  │     └─ your repo with CLAUDE.md, .claude/, docs/, scripts/     │\n  │                                                                │\n  │  /tmp/staged/                                                  │\n  │     └─ runbook + maintenance scripts staged into RAM           │\n  │        (survive the later umount -R /mnt/target-root)          │\n  └────────────────────────────────────────────────────────────────┘\n                                                     │\n                                                     ▼\n  ┌────────────────────────────────────────────────────────────────┐\n  │  AI session, cwd = /mnt/target-root/\u003cyour repo\u003e                │\n  │     - reads CLAUDE.md + .claude/* automatically                │\n  │     - reads docs/runbooks/\u003cyour-runbook\u003e.md                    │\n  │     - asks for JA before each destructive step                 │\n  │     - quotes rollback instructions from the runbook on failure │\n  └────────────────────────────────────────────────────────────────┘\n```\n\nThe key design decision is that **the AI does not need to know your project\nin advance**. It learns the project at session start by reading the files\nthe operator's team has already written. The toolkit only provides the\ndelivery mechanism.\n\n## Repository Layout\n\n```\nclaude-code-live-usb/\n├── 1-stick-build/        How to turn a vanilla Live-USB into a toolkit stick.\n├── 2-stick-payload/      The five scripts that run on the stick + briefing template.\n├── 3-case-study/         A real LVM shrink/grow operation, end to end.\n├── docs/                 Architecture, OAuth lifecycle, gotchas, extension.\n├── examples/             More briefing templates (network, disk, certs).\n└── README.md             This file.\n```\n\nEach numbered directory has its own README explaining the contents.\n\n## Use Cases\n\n**A good fit:**\n\n- Offline maintenance on a single bare-metal Linux box where the operation\n  cannot run online: LVM shrink, disk replacement in an MD-RAID mirror,\n  offline certificate renewal, netplan repair from rescue.\n- Solo operators without a colleague to pair with during an out-of-hours\n  maintenance window.\n- Setups built on MD-RAID + LVM, which the bundled `mount-target.sh`\n  targets directly.\n\n**Not a good fit:**\n\n- Operations that can run online (LVM extend, most `apt upgrade`). Do them\n  online and skip the live boot.\n- Fleet or mass provisioning. Use PXE + kickstart or configuration\n  management instead.\n- Encrypted root volumes (unlock LUKS by hand first) or non-Linux targets.\n- ZFS or btrfs-raid setups, without first adapting `mount-target.sh`. See\n  [docs/EXTENDING.md](docs/EXTENDING.md).\n\n## Use the Case Study to Learn the Pattern\n\nIf you only have 20 minutes, read [3-case-study/README.md](3-case-study/README.md)\nand the [operations report](3-case-study/OPERATIONS_REPORT.md). The report\ncovers the first run on a production machine: three correction iterations,\ntwo of which were bugs the AI found in the orchestration script before they\ncaused damage. That is the kind of feedback loop the architecture is\ndesigned to produce.\n\n## Adapt the Pattern to Your Maintenance Workflow\n\nThe LVM case is one application. The pattern (briefing + runbook +\nJA-gated destructive steps) is generic. See:\n\n- [examples/briefing-network-recovery.md](examples/briefing-network-recovery.md)\n- [examples/briefing-disk-replacement.md](examples/briefing-disk-replacement.md)\n- [examples/briefing-cert-renewal.md](examples/briefing-cert-renewal.md)\n- [docs/EXTENDING.md](docs/EXTENDING.md)\n\n## Known Limitations\n\n| Limitation | What this means in practice |\n|---|---|\n| OAuth refresh-token rotation | The stick and your workstation will fight over the token. Either treat the stick as \"burn-after-use\" or re-authenticate on whichever device you used last. Detailed in [docs/OAUTH_TOKEN_LIFECYCLE.md](docs/OAUTH_TOKEN_LIFECYCLE.md). |\n| Stick is a bearer credential | Anyone holding the stick can run AI sessions as the token owner. Encrypt with LUKS if you carry it through hostile environments. See [Mitigation 4 in OAUTH_TOKEN_LIFECYCLE.md](docs/OAUTH_TOKEN_LIFECYCLE.md#mitigation-4-encrypt-the-stick-with-luks). |\n| Ubuntu Desktop assumption | Server ISO works too, but the GNOME auto-mount conveniences do not apply. You mount the toolkit partition by hand (see [docs/GOTCHAS.md](docs/GOTCHAS.md), entry 10). |\n| Single-architecture binary | The bundled AI CLI is x86-64. ARM hosts need an ARM binary in `bin/`. |\n| Project layout assumed | `mount-target.sh` and `start-claude.sh` default to `home/admin/myrepo` as the repository path inside the target LV. Override with `TARGET_REPO_PATH=path/to/your/repo` if your layout differs (no leading slash). |\n| MD-RAID + LVM assumed | The mount script targets MD-RAID arrays and LVM volume groups. ZFS, btrfs-raid, or plain disk setups need adaptation (see [docs/EXTENDING.md](docs/EXTENDING.md)). |\n| No Memory transfer | Project memory under `~/.claude/projects/-\u003ccwd-hash\u003e-/` is not loaded in the live session, because the cwd changes. Only `CLAUDE.md` and `.claude/*` files travel with the repository. |\n\n## Why \"Claude Code\" specifically?\n\nClaude Code is the AI CLI this project was developed against, because of\nits project-context loading (it walks the cwd looking for `CLAUDE.md` and\n`.claude/` files) and its ability to read multiple documents into a single\nsession. The architecture would work with other project-aware AI CLIs that\npresent a similar binary interface; only the `cc-setup.sh` payload would\nchange. Pull requests adapting the toolkit to other tools are welcome (see\n[CONTRIBUTING.md](CONTRIBUTING.md)).\n\n## Documentation\n\n- [1-stick-build/README.md](1-stick-build/README.md) — build the toolkit stick\n- [2-stick-payload/README.md](2-stick-payload/README.md) — what each stick script does\n- [3-case-study/README.md](3-case-study/README.md) — the worked LVM example, end to end\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — why the toolkit is shaped this way\n- [docs/EXTENDING.md](docs/EXTENDING.md) — adapt the pattern to your own workflow\n- [docs/OAUTH_TOKEN_LIFECYCLE.md](docs/OAUTH_TOKEN_LIFECYCLE.md) — the token-rotation trade-off\n- [docs/GOTCHAS.md](docs/GOTCHAS.md) — non-obvious things that bit real operators\n- [CHANGELOG.md](CHANGELOG.md) · [SECURITY.md](SECURITY.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)\n\n## Contributing\n\nBug reports, briefing templates for new maintenance categories, and\nadaptations to other project-aware AI CLIs are welcome. See\n[CONTRIBUTING.md](CONTRIBUTING.md).\n\n## See Also\n\n- [linux-server-reboot-management](https://github.com/fidpa/linux-server-reboot-management) — the complement: graceful orchestration for *planned* reboots, where this toolkit covers the *escalated* offline case.\n- [step-ca-internal-pki](https://github.com/fidpa/step-ca-internal-pki) — one kind of target the cert-renewal briefing template applies to.\n- [Diataxis](https://diataxis.fr/) — the documentation framework the `docs/` follow.\n\n## License\n\n[MIT](LICENSE). Copyright (c) 2026 Marc Allgeier.\n\n## Author\n\nMarc Allgeier ([@fidpa](https://github.com/fidpa))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffidpa%2Fclaude-code-live-usb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffidpa%2Fclaude-code-live-usb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffidpa%2Fclaude-code-live-usb/lists"}