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. 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.

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/<ai-binary>                          │              │
  └────────────────────────────────────────────────────────────────┘
                                                     │
                                                     ▼
  ┌────────────────────────────────────────────────────────────────┐
  │  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/<your repo>                │
  │     - reads CLAUDE.md + .claude/* automatically                │
  │     - reads docs/runbooks/<your-runbook>.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.

Use the Case Study to Learn the Pattern

If you only have 20 minutes, read 3-case-study/README.md and the operations report. 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-disk-replacement.md
• examples/briefing-cert-renewal.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.
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.
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, 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).
No Memory transfer	Project memory under ~/.claude/projects/-<cwd-hash>-/ 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).

Documentation

• 1-stick-build/README.md — build the toolkit stick
• 2-stick-payload/README.md — what each stick script does
• 3-case-study/README.md — the worked LVM example, end to end
• docs/ARCHITECTURE.md — why the toolkit is shaped this way
• docs/EXTENDING.md — adapt the pattern to your own workflow
• docs/OAUTH_TOKEN_LIFECYCLE.md — the token-rotation trade-off
• docs/GOTCHAS.md — non-obvious things that bit real operators
• CHANGELOG.md · SECURITY.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.

See Also

• linux-server-reboot-management — the complement: graceful orchestration for planned reboots, where this toolkit covers the escalated offline case.
• step-ca-internal-pki — one kind of target the cert-renewal briefing template applies to.
• Diataxis — the documentation framework the docs/ follow.

License

MIT. Copyright (c) 2026 Marc Allgeier.

Author

Marc Allgeier (@fidpa)