u-claw/bootable/README.md

# Bootable Linux USB

> Turn any computer into an AI workstation — boot from the drive, no operating
> system required on the machine itself.

## How this differs from the portable build

The portable build (`portable/`) needs the computer to already run Windows or
macOS. This one does not need the machine to have an operating system at all:
it boots Ubuntu off the drive and runs U-Claw inside it.

That makes it the answer for a machine that is locked down, wiped, or running
something you cannot install onto.

## Self-contained on purpose

This directory does not reference `portable/`, `u-claw-app/` or anything else in
the repository. Every script hardcodes its own URLs and paths. A change here
cannot break another module, and a change elsewhere cannot break this.

There is also a standalone mirror at
[u-claw-linux](https://gitea.fanghe.it.com/zhenghy/u-claw-linux) with the same
contents, for cloning it on its own.

## What ends up on the drive

```
Ventoy boot area (hidden partition)
  BIOS + UEFI dual-mode boot, Ventoy 1.0.99

Ventoy data partition (visible)
  ubuntu-24.04.4-desktop-amd64.iso   5.8 GB
  persistence.dat                    20 GB
  ventoy/ventoy.json                 config
  u-claw-linux/
    ├── setup-openclaw.sh
    └── start-openclaw.sh
```

| Choice | Why |
|---|---|
| **Ventoy 1.0.99** | Drop an ISO in and it boots — no burning, and several systems can share the drive |
| **Ubuntu 24.04 LTS** | Long-term support, the widest hardware driver coverage |
| **casper-rw persistence** | Lets a live USB keep data across reboots |

## What you need

| | |
|---|---|
| USB drive | **32 GB or larger.** USB 3.0 strongly recommended — on 2.0 everything is painful |
| Build machine | Windows 10/11, PowerShell 5.1+ |
| Target machine | x86_64 (Intel or AMD), any brand |
| Network | Needed once, when installing OpenClaw |

## Building it — four steps

Open PowerShell **as Administrator** on Windows:

```powershell
cd path\to\u-claw\bootable

.\1-prepare-usb.ps1          # Write Ventoy to the drive — THIS FORMATS IT
.\2-download-iso.ps1         # Download Ubuntu 24.04 (~5.8 GB)
.\3-create-persistence.ps1   # Create the persistence image (20 GB default)
.\4-copy-to-usb.ps1          # Copy everything onto the drive
```

### What each step does

**1 · Write Ventoy** — lists your USB devices for confirmation, downloads Ventoy,
then hands you its GUI to pick the drive and click Install.
**This erases the drive. Back it up first.**

**2 · Download Ubuntu** — fetches the 24.04.4 desktop ISO from
`releases.ubuntu.com`, verifies its SHA256, and caches it so a retry does not
re-download 5.8 GB.

**3 · Create persistence** — the step that actually decides whether this works.

- **With WSL installed** → creates a properly formatted ext4 image directly
- **With only docker-desktop's WSL** → falls back to `/sbin/mkfs.ext4`
- **With no WSL at all** → creates an empty sparse file that **you must format
  by hand** on first boot (see below)

The volume label must be `casper-rw` — that is the name Ubuntu looks for.

**4 · Copy to the drive** — finds the Ventoy drive by its label, checks free
space, copies the ISO, `persistence.dat`, `ventoy.json` and the setup scripts.

## When the scripts fail

Reported by @wzf9 in issue #28. Useful when a download fails, the network is
unreliable, or you are building offline.

**Ventoy would not download or install**

Get the Windows build from https://github.com/ventoy/Ventoy/releases, unzip,
run `Ventoy2Disk.exe`, pick the drive, click Install. It formats the drive.

**The ISO would not download**

Fetch it yourself:
- https://releases.ubuntu.com/24.04/ubuntu-24.04.4-desktop-amd64.iso
- https://releases.ubuntu.com/24.04/SHA256SUMS

Put the ISO at `bootable\.download-cache\ubuntu-24.04.4-desktop-amd64.iso`, then
check it:

```powershell
(Get-FileHash -Algorithm SHA256 ".\.download-cache\ubuntu-24.04.4-desktop-amd64.iso").Hash -eq "3a4c9877b483ab46d7c3fbe165a0db275e1ae3cfe56a5657e5a47c2f99a99d1e"
```

**The persistence file is empty (no WSL)**

Boot into Ubuntu once, then:

```bash
sudo mkfs.ext4 -F -L casper-rw /media/*/Ventoy/persistence.dat
```

**Reboot after formatting** — persistence does not take effect until you do.

**The copy step failed**

Put these on the Ventoy data partition by hand:

| From | To (drive root) |
|---|---|
| `bootable\linux-setup\` | `u-claw-linux\` |
| `bootable\ventoy\` | `ventoy\` |
| `bootable\.download-cache\persistence.dat` | `persistence.dat` |
| `bootable\.download-cache\ubuntu-24.04.4-desktop-amd64.iso` | (same name) |

## Using it

### First time

1. Plug the drive into the target machine
2. Power on and press the boot-menu key:

| Brand | Key |
|---|---|
| Dell | F12 |
| Lenovo | F12 |
| HP | F9 |
| ASUS | F2 or DEL |
| Acer | F12 |
| MSI | F11 |
| Others | F12 or F2 usually; check the splash screen |

3. Choose the USB device, then Ubuntu from the Ventoy menu
4. Wait for the desktop — one to three minutes off a USB drive is normal
5. Connect to Wi-Fi
6. Open a terminal (`Ctrl+Alt+T`) and run:

```bash
sudo bash /media/*/Ventoy/u-claw-linux/setup-openclaw.sh
```

7. A **U-Claw AI Assistant** icon appears on the desktop
8. Double-click it, then paste an API key in the browser

### After that

Plug in, boot, double-click the icon. Everything you set up is still there.

## What `setup-openclaw.sh` does

| Step | |
|---|---|
| 1 | Check it is running as root — it needs `sudo` |
| 2 | Install `curl` and `xdg-utils` |
| 3 | Create `/opt/u-claw/{runtime,core,data}` |
| 4 | Download Node.js from `nodejs.org` |
| 5 | Write `package.json` |
| 6 | Install OpenClaw and the QQ plugin from `registry.npmjs.org` |
| 7 | Write the default config — gateway and token |
| 8 | Install the start script into `/opt/u-claw/` |
| 9 | Create the desktop shortcut, optionally starting on login |

## Configuration

### `ventoy/ventoy.json`

```json
{
  "persistence": [
    {
      "image": "/ubuntu-24.04.4-desktop-amd64.iso",
      "backend": "/persistence.dat",
      "autosel": 1
    }
  ]
}
```

Tells Ventoy to attach `persistence.dat` when booting that ISO. `autosel: 1`
skips the confirmation prompt.

### Environment on Linux

| Variable | Value |
|---|---|
| `OPENCLAW_HOME` | `/opt/u-claw/data/.openclaw` |
| `OPENCLAW_STATE_DIR` | `/opt/u-claw/data/.openclaw` |
| `OPENCLAW_CONFIG_PATH` | `/opt/u-claw/data/.openclaw/openclaw.json` |

## Files

```
bootable/
├── README.md                    this file
├── 1-prepare-usb.ps1            write Ventoy
├── 2-download-iso.ps1           download Ubuntu
├── 3-create-persistence.ps1     create the persistence image
├── 4-copy-to-usb.ps1            copy onto the drive
├── linux-setup/
│   ├── format-persistence.sh    format the persistence image
│   ├── setup-openclaw.sh        install OpenClaw
│   ├── start-openclaw.sh        launcher
│   └── openclaw.desktop         desktop shortcut
└── ventoy/
    └── ventoy.json              persistence config
```

## Things learned the hard way

**An unformatted `persistence.dat` drops Ubuntu into initramfs.** Ventoy cannot
mount a file with no ext4 filesystem in it, and the boot fails in a way that
gives no hint about the cause. To check whether a file is actually formatted,
read two bytes at offset 1080 — they should be `0x53 0xEF`, the little-endian
form of the ext4 magic number `0xEF53`.

**Formatting requires a reboot.** Running `mkfs.ext4` and continuing in the same
session looks like it worked and silently does not persist.

**Drive quality matters more than you would expect.** Cheap unbranded drives fail
in ways that look like software problems. Use USB 3.0, plug into the board
directly rather than through a hub, and prefer 32 GB+ (5.8 GB ISO + 20 GB
persistence + overhead leaves little room otherwise).

**Sizing**: 20 GB persistence on a 32 GB drive, 40 GB+ on a 64 GB drive.

## Troubleshooting

| Problem | Fix |
|---|---|
| Will not boot from USB | In BIOS: disable Secure Boot, enable USB boot. Try both UEFI and Legacy/CSM |
| No Ubuntu in the Ventoy menu | The ISO must be in the root of the Ventoy data partition |
| Boot stops at initramfs | `persistence.dat` is not formatted. `mkfs.ext4 -F -L casper-rw`, then reboot |
| Data lost on reboot | Same cause — check the file is ext4 and the label is exactly `casper-rw` |
| No USB boot entry at all | Try another port; some machines disable USB boot in BIOS by default |
| Desktop takes ages to load | Normal off a USB drive. USB 3.0 on a USB 3.0 port helps a lot |
| OpenClaw install fails | Check the network — it needs `nodejs.org` and `registry.npmjs.org` |
| Wi-Fi does not work | Ubuntu 24.04 covers most chipsets; otherwise tether over USB from a phone |
| Browser does not open | Go to `http://localhost:18789` yourself |
| Port already in use | OpenClaw uses 18789–18799. Close the terminal window and open it again |
| Wrong screen resolution | Settings → Displays |

**Performance**: running off a USB drive is slower than a disk — that is
physics, not a bug. Inference happens at your model provider, so conversation
speed is unaffected; only startup and file operations are slower.

For anything not covered here, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).