Magic Stick

Standardized portable environment on a bootable USB drive

• SourceForge — raw ISO

Important

Flash the ISO directly:

sudo dd if=magic_stick_0.1.8.iso of=/dev/sdX bs=4M status=progress && sync

---

Why Magic Stick?

You’re a field technician, trainer, or nomadic developer. Every time you sit at a different computer, you lose 30 minutes setting it up. Magic Stick eliminates that problem: a USB drive that boots a complete, identical environment on any PC.

• Training: every student gets the same drive, ready to work on day one

• FTTH/Network technician: full network diagnostics regardless of the host machine

• Nomadic dev: find your full stack (Docker, Java, Ollama) on any computer

• Tech teams: shared standardized environment, zero time wasted on setup

---

How it works

Magic Stick uses an A/B partition system with persistence:

Partition	Size	Role
System A	~8 GB	Active Xubuntu live system (default boot)
System B	~8 GB	Backup Xubuntu live system (inactive)
Persistence	Remaining space	User data + software config

Atomic updates

1. update-system.sh detects the active partition (A or B)

2. It writes the new ISO to the inactive partition

3. It flips the GRUB boot flag

4. On next boot: new version is active

5. Something went wrong? Reboot into the previous partition — instant rollback

6. The Persistence partition is never touched

---

Included software

Category	Software
Desktop	Xubuntu Desktop (XFCE)
Containerization	Docker CE + Docker Compose, Podman
Local AI	Ollama (on-device LLM)
Development	SDKMAN + JDK 25 Temurin, Git, curl, wget, jq, JetBrains Toolbox
JavaScript/Node	NVM, Node.js, pnpm
Python	Python 3.14.4, uv package manager
Network/FTTH	nmap, iperf3, Wireshark, tshark, traceroute, dnsutils
System diagnostics	htop, ncdu, tree, lshw, smartmontools
Search/Navigation	ripgrep, fd, fzf
Git tools	lazygit
HTTP/REST	xh
Task runner	just
Package manager	Flatpak
Shell	zsh + oh-my-zsh, starship
Media	opencode, graphify, ffmpeg
SSH/Transfer	OpenSSH client, rsync, tmux, terminator

---

Quick start

Prerequisites

• A USB drive with at least 32 GB (64 GB recommended)

Download the ISO

• SourceForge — raw ISO

Note	The ISO is built by GitHub Actions on every tag push. No local build needed.

Flash to a USB drive

# Identify the USB drive
lsblk

# Flash (WARNING: erases all data on the target device)
sudo scripts/flash.sh /dev/sdX

Update the system (A/B)

# Update the inactive partition
sudo scripts/update-system.sh /dev/sdX

# If the new system fails to boot:
# select the previous partition in the GRUB menu

---

Project architecture

magic_stick/
├── build/                             # live-build output (generated ISOs)
├── config/
│   ├── live-build/
│   │   ├── package-lists/            # Package lists
│   │   ├── hooks/                     # chroot + binary hooks
│   │   ├── includes.chroot/          # Files included in the system
│   │   └── includes.binary/          # Files included in the ISO
│   └── overrides/
│       └── skel/                      # Custom /etc/skel (home template)
├── scripts/
│   ├── build.sh                       # ISO build via Docker (entry point)
│   ├── build-inner.sh                # ISO build (inside Docker)
│   ├── flash.sh                       # USB flash
│   ├── test-boot.sh                   # QEMU boot test
│   ├── update-system.sh               # A/B update
│   ├── install-software.sh            # Software in chroot
│   └── verify.sh                      # ISO verification
├── src/
│   └── main/resources/                # Gradle build resources
├── Dockerfile                         # Docker image for the build
├── build.gradle.kts                   # Gradle build config
└── .github/workflows/build.yml       # CI/CD pipeline

---

Recommended partitioning (64 GB drive)

Partition	Size	Type	Flag
1 (System A)	8 GB	squashfs	boot
2 (System B)	8 GB	squashfs	-
3 (Persistence)	~48 GB	ext4	-

The Persistence partition uses persistence.conf with / union to save data between sessions.

---

Security

• No personal data in the ISO — SSH keys and user files go in the Persistence partition

• Automatic rollback if the new system fails to boot

• Persistent data is never touched by system updates

• Atomic updates: if it breaks, revert to the previous version with a single reboot

---

Project status

EPIC	Status
EPIC 1: Project initialization	✅ Done
EPIC 2: Xubuntu base ISO build	✅ Done — Download v0.1.8
EPIC 3: A/B partition + Persistence	✅ Done
EPIC 4: Software (Ollama, Docker, SDKMAN, tools)	✅ Done
EPIC 5: XFCE customization	✅ Done
EPIC 6: A/B update script	✅ Done
EPIC 8: Docker CLI image	✅ Done

Docker CLI image

A cheroliv/magic-stick-cli Docker image is available on Docker Hub. It mirrors the CLI software stack from the live-build chroot (no GUI) for CI/CD jobs and Ollama Cloud.

Pull

docker pull cheroliv/magic-stick-cli:latest

docker-compose.yml

services:
  magic-stick-cli:
    image: cheroliv/magic-stick-cli:latest
    stdin_open: true
    tty: true
    working_dir: /workspace
    volumes:
      - ./:/workspace
    deploy:
      resources:
        limits:
          memory: 4G

GitHub Actions job

jobs:
  my-job:
    runs-on: ubuntu-latest
    container: cheroliv/magic-stick-cli:latest
    steps:
      - uses: actions/checkout@v4
      - run: python3 script.py
      - run: uv run --with requests fetch.py
      - run: xh GET https://api.example.com/data

Authentication Ollama Cloud

Caution

Never store credentials in image layers.

docker run --rm -e OLLAMA_DEVICE_KEY="$OLLAMA_DEVICE_KEY" cheroliv/magic-stick-cli ollama login

Distinction with live system

• The Docker image is CLI-only — no XFCE, no JetBrains Toolbox, no VS Code

• The live ISO is the full bootable desktop environment

• Both share the same pinned tool versions (versions.sh)

---

---

License

Apache License 2.0