Skip to content

USB installation

Before you start

Use a dedicated x86-64 computer, an empty USB drive of at least 8 GB, a second computer that can download and write a disk image, and a browser on the same private network. Use the prebuilt reduced installer. You do not need Git, Docker or a local image build. Check requirements.

The image writer erases the selected USB drive. Ubuntu installation can erase the selected target disk. Back up data and verify each device before confirming.

1. Download the installer

Download these two files into the same folder:

The download details and build evidence identify the exact source and checks. Choose the .img asset, not GitHub's automatically generated “Source code” archives. This image uses Ubuntu Server 26.04.1 AMD64 and follows Magic Stick's main channel at first boot.

Internet access is required during installation. The image keeps Ubuntu's signed main package pool so the live installer can configure supported Wi-Fi before it has Internet access. The large optional restricted driver archive is omitted; remaining packages come from your selected Ubuntu mirror. The live kernel, firmware and installer remain included. No GitHub token, wireless credentials or default user password are embedded.

The earlier online-only candidate passed an Ethernet installation on 24 September 2026, but could not bootstrap Wi-Fi support because it removed all local package archives. The reduced image corrects that packaging defect. Its automated media checks do not replace a physical Wi-Fi installation test; GPU and inference compatibility are checked separately.

Verify the checksum before writing the drive. On Linux, in the download folder:

sha256sum -c magicstick-installer-main-amd64-reduced-be5ea39c2b30b3aa.img.sha256

On macOS, use shasum -a 256 -c with the same checksum filename. The result must be OK. On Windows, use Get-FileHash in PowerShell and compare its SHA256 value with the first value in the downloaded .sha256 file:

Get-FileHash .\magicstick-installer-main-amd64-reduced-be5ea39c2b30b3aa.img -Algorithm SHA256

Stop if the checksum does not match. Local build scripts are development tools, not an installation prerequisite. develop images are for explicit development testing; do not substitute them for the main download above.

2. Write the USB drive

  1. Open a USB image-writing application that supports raw .img disk images. Examples for the computer you use to prepare the stick:

    • Windows: balenaEtcher or Rufus. In Rufus, choose DD Image mode if asked, not ISO mode, so the complete disk layout including CIDATA is preserved.
    • macOS: balenaEtcher; select the download for your Intel or Apple Silicon Mac.
    • Linux: balenaEtcher or GNOME Disks, using Restore Disk Image.

    Download the writer from its official site above or your distribution's software manager. Select the downloaded Magic Stick .img, not an Ubuntu ISO.

  2. Select the downloaded image and the whole USB drive, checking its model and capacity. Writing erases that drive; do not select your computer's disk.

  3. Write the image and allow the application's verification to finish. Copying the .img into an ordinary USB folder does not make it bootable.
  4. Reconnect the USB drive if necessary. Open the small partition labelled CIDATA; do not format another partition if your operating system prompts.
  5. In meta-data, set both values to a unique name for your appliance:
instance-id: magicstick-01
local-hostname: magicstick-01

Leave user-data unchanged for the normal public installation. Network, mirror, administrator account and target disk are chosen during installation. Save the file as plain text without changing its name, then safely eject the drive. Optional command-line writers are documented with the developer media tools.

3. Install the computer

  1. Boot the target computer from USB and choose Try or Install Ubuntu Server.
  2. In network configuration, configure an Ethernet or supported Wi-Fi interface. Enter the SSID/password locally; they are not embedded in the public image.
  3. Verify an IP address and Internet access. Unsupported live-system drivers or captive portals require another connection; a plugged cable alone is not proof of connectivity.
  4. Review the package mirror. A country mirror suggested by GeoIP is not a speed measurement. Use a reachable mirror containing the selected Ubuntu release.
  5. Create the Linux administration user and optionally enable SSH. This is not the later dashboard account. Review the target disk and confirm installation.
  6. Wait for the installer to power off, remove the stick, then power on again.

Provisioning continues after the first Ubuntu boot. Package and image downloads can take several minutes. Cloud-init hands off to the setup console on virtual terminal 9; boot logs remain on terminal 1. On a computer whose monitor is connected to an NVIDIA GPU, the fetched host playbook may schedule one additional restart after it installs the display driver. Leave the USB stick removed and wait for the setup console to return. No new USB image is needed solely for a host-playbook update when the stick follows main.

4. Complete setup

Use the private setup URL, one-time code and certificate fingerprint on the console. If needed, sign in locally or over SSH and run:

sudo magicstick setup show

Follow first administrator setup, then verify installation.

If installation stops

sudo cloud-init status --long
sudo journalctl -u cloud-final -b --no-pager
sudo journalctl -u k3s -b --no-pager

Keep private values out of support logs. See platform diagnostics. Do not reinstall or recreate the first-run marker merely to retry a failed download.