https://github.com/fidpa/claude-code-live-usb
Bring an AI CLI onto an Ubuntu Live-USB as a JA-gated lead operator for bare-metal maintenance (LVM, MD-RAID, recovery).
https://github.com/fidpa/claude-code-live-usb
ai-tools bare-metal bash devops linux live-usb lvm mdadm recovery sre sysadmin ubuntu
Last synced: 4 days ago
JSON representation
Bring an AI CLI onto an Ubuntu Live-USB as a JA-gated lead operator for bare-metal maintenance (LVM, MD-RAID, recovery).
- Host: GitHub
- URL: https://github.com/fidpa/claude-code-live-usb
- Owner: fidpa
- License: other
- Created: 2026-05-27T21:11:01.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-27T21:27:52.000Z (about 2 months ago)
- Last Synced: 2026-07-17T21:39:56.088Z (4 days ago)
- Topics: ai-tools, bare-metal, bash, devops, linux, live-usb, lvm, mdadm, recovery, sre, sysadmin, ubuntu
- Language: Shell
- Size: 74.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Claude Code on a Live-USB
**Bring an AI CLI onto the Ubuntu Live-USB you booted from, as a JA-gated lead operator for bare-metal maintenance.**
> Boot a vanilla Ubuntu Live-USB. Run one bootstrap script. Now an AI coding
> agent is sitting at the same terminal as you, has read your project's
> documentation, and is ready to talk you through a bare-metal maintenance
> operation.
## The Problem
Bare-metal Linux maintenance is exactly the kind of work where you want a
second set of eyes: shrinking an LVM volume, replacing a failed disk,
recovering from a broken initramfs, renewing a certificate that lives
inside a recovery image. But it is also the work where you cannot have
those eyes. The machine is in single-user mode, the network is unreliable,
the clock is wrong, and your normal tools (browser, IDE, ChatGPT tab) are
on a different continent of your filesystem.
The standard answer is "print the runbook and pray". This project's answer
is: bring the AI with you, on the same USB stick you booted from.
## What You Get
A ~488 MB usable ext4 partition (carved from a `+512M` sgdisk slot; ext4
overhead and root-reserved blocks account for the difference) on your
existing Live-USB containing:
- The AI CLI binary, ready to run as `root` after the bootstrap.
- A 5-script payload on the stick (`find-stick`, `cc-setup`,
`mount-target`, `pre-resize-snapshot`, `start-claude`) plus one
stick-builder (`build-stick`) that runs on your workstation. The
case study adds a 7th script (`shrink-lv-extend-other`) as a worked
maintenance example.
- A "briefing" pattern that lets the AI act as the **lead operator** for
a runbook. You answer `JA`/`NEIN`, it does the orchestration.
- A worked example (LVM shrink/grow under MD-RAID) with the operations
report from the first real-world run, including the three corrections
it took to get right.
## Requirements
| Component | Needed for | Notes |
|---|---|---|
| Ubuntu Live-USB | always | Desktop ISO recommended (GNOME auto-mount); Server ISO works with manual mounting |
| 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. |
| Free space on the stick | always | ~512 MB beyond the ISO partition; a 16 GB+ stick is comfortable |
| `mdadm`, `lvm2`, `e2fsprogs` | MD-RAID / LVM targets | installed into the live session, not bundled in the Desktop ISO |
| Bash | always | 4.0+, present on any current Ubuntu |
## Quick Start (operator view)
You have already booted the Live-USB. You are at a terminal as `root`.
```bash
STICK=$(/media/ubuntu/CC-TOOLS/find-stick.sh)
bash $STICK/cc-setup.sh
DEBIAN_FRONTEND=noninteractive apt-get install -y mdadm lvm2 e2fsprogs
bash $STICK/mount-target.sh
bash $STICK/start-claude.sh
```
That is the entire memorised sequence. After `start-claude.sh` the AI session
takes over: it reads `CLAUDE.md` and `.claude/*` from your repository, reads
the runbook in `docs/runbooks/...`, and starts asking the questions a careful
operator would ask (*"Is the database VM shut down? Are you sure the disk
serial number matches the one in the runbook?"*).
## How It Works (architecture in one screen)
```
┌────────────────────────────────────────────────────────────────┐
│ Vanilla Ubuntu Desktop Live-USB │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ sdX1 iso9660 │ │ sdX2 vfat ESP│ │ sdX4 ext4 "CC-TOOLS" │ │
│ │ (Ubuntu ISO) │ │ (boot) │ │ this project │ │
│ └──────────────┘ └──────────────┘ └──────────┬───────────┘ │
│ │ │
│ /media/ubuntu/CC-TOOLS/ ← GNOME automount │ │
│ ├─ find-stick.sh ← memorize one path │ │
│ ├─ cc-setup.sh ← installs AI + creds │ │
│ ├─ mount-target.sh ← mdadm/vgchange/mount │ │
│ ├─ start-claude.sh ← shows briefing, runs │ │
│ └─ bin/ │ │
└────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────┐
│ Target machine's NVMe (read-only mounted at /mnt/target-root) │
│ └─ your repo with CLAUDE.md, .claude/, docs/, scripts/ │
│ │
│ /tmp/staged/ │
│ └─ runbook + maintenance scripts staged into RAM │
│ (survive the later umount -R /mnt/target-root) │
└────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────┐
│ AI session, cwd = /mnt/target-root/ │
│ - reads CLAUDE.md + .claude/* automatically │
│ - reads docs/runbooks/.md │
│ - asks for JA before each destructive step │
│ - quotes rollback instructions from the runbook on failure │
└────────────────────────────────────────────────────────────────┘
```
The key design decision is that **the AI does not need to know your project
in advance**. It learns the project at session start by reading the files
the operator's team has already written. The toolkit only provides the
delivery mechanism.
## Repository Layout
```
claude-code-live-usb/
├── 1-stick-build/ How to turn a vanilla Live-USB into a toolkit stick.
├── 2-stick-payload/ The five scripts that run on the stick + briefing template.
├── 3-case-study/ A real LVM shrink/grow operation, end to end.
├── docs/ Architecture, OAuth lifecycle, gotchas, extension.
├── examples/ More briefing templates (network, disk, certs).
└── README.md This file.
```
Each numbered directory has its own README explaining the contents.
## Use Cases
**A good fit:**
- Offline maintenance on a single bare-metal Linux box where the operation
cannot run online: LVM shrink, disk replacement in an MD-RAID mirror,
offline certificate renewal, netplan repair from rescue.
- Solo operators without a colleague to pair with during an out-of-hours
maintenance window.
- Setups built on MD-RAID + LVM, which the bundled `mount-target.sh`
targets directly.
**Not a good fit:**
- Operations that can run online (LVM extend, most `apt upgrade`). Do them
online and skip the live boot.
- Fleet or mass provisioning. Use PXE + kickstart or configuration
management instead.
- Encrypted root volumes (unlock LUKS by hand first) or non-Linux targets.
- ZFS or btrfs-raid setups, without first adapting `mount-target.sh`. See
[docs/EXTENDING.md](docs/EXTENDING.md).
## Use the Case Study to Learn the Pattern
If you only have 20 minutes, read [3-case-study/README.md](3-case-study/README.md)
and the [operations report](3-case-study/OPERATIONS_REPORT.md). The report
covers the first run on a production machine: three correction iterations,
two of which were bugs the AI found in the orchestration script before they
caused damage. That is the kind of feedback loop the architecture is
designed to produce.
## Adapt the Pattern to Your Maintenance Workflow
The LVM case is one application. The pattern (briefing + runbook +
JA-gated destructive steps) is generic. See:
- [examples/briefing-network-recovery.md](examples/briefing-network-recovery.md)
- [examples/briefing-disk-replacement.md](examples/briefing-disk-replacement.md)
- [examples/briefing-cert-renewal.md](examples/briefing-cert-renewal.md)
- [docs/EXTENDING.md](docs/EXTENDING.md)
## Known Limitations
| Limitation | What this means in practice |
|---|---|
| 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). |
| 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). |
| 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). |
| Single-architecture binary | The bundled AI CLI is x86-64. ARM hosts need an ARM binary in `bin/`. |
| 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). |
| 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)). |
| No Memory transfer | Project memory under `~/.claude/projects/--/` is not loaded in the live session, because the cwd changes. Only `CLAUDE.md` and `.claude/*` files travel with the repository. |
## Why "Claude Code" specifically?
Claude Code is the AI CLI this project was developed against, because of
its project-context loading (it walks the cwd looking for `CLAUDE.md` and
`.claude/` files) and its ability to read multiple documents into a single
session. The architecture would work with other project-aware AI CLIs that
present a similar binary interface; only the `cc-setup.sh` payload would
change. Pull requests adapting the toolkit to other tools are welcome (see
[CONTRIBUTING.md](CONTRIBUTING.md)).
## Documentation
- [1-stick-build/README.md](1-stick-build/README.md) — build the toolkit stick
- [2-stick-payload/README.md](2-stick-payload/README.md) — what each stick script does
- [3-case-study/README.md](3-case-study/README.md) — the worked LVM example, end to end
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — why the toolkit is shaped this way
- [docs/EXTENDING.md](docs/EXTENDING.md) — adapt the pattern to your own workflow
- [docs/OAUTH_TOKEN_LIFECYCLE.md](docs/OAUTH_TOKEN_LIFECYCLE.md) — the token-rotation trade-off
- [docs/GOTCHAS.md](docs/GOTCHAS.md) — non-obvious things that bit real operators
- [CHANGELOG.md](CHANGELOG.md) · [SECURITY.md](SECURITY.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
## Contributing
Bug reports, briefing templates for new maintenance categories, and
adaptations to other project-aware AI CLIs are welcome. See
[CONTRIBUTING.md](CONTRIBUTING.md).
## See Also
- [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.
- [step-ca-internal-pki](https://github.com/fidpa/step-ca-internal-pki) — one kind of target the cert-renewal briefing template applies to.
- [Diataxis](https://diataxis.fr/) — the documentation framework the `docs/` follow.
## License
[MIT](LICENSE). Copyright (c) 2026 Marc Allgeier.
## Author
Marc Allgeier ([@fidpa](https://github.com/fidpa))