# Someone Build a OS for Claude Code

> Source: <https://github.com/mateolafalce/claudios/blob/main/README.md>
> Published: 2026-06-21 18:58:37+00:00

**What if your entire OS was just Claude Code?**

A Linux distro that boots straight into [Claude Code](https://claude.ai/code). No desktop. No window manager. Just a TTY and an AI agent with full system access. Built on Ubuntu 24.04 LTS.

If Claude Code can install packages, write and run code, manage files, browse the internet, and operate your entire machine — what do you need a desktop for?

ClaudiOS takes this idea to its logical conclusion: the operating system gets out of the way and Claude becomes the interface. You boot, you log in, and you're talking to Claude. That's it.

Flash it to a USB stick, boot any x86_64 machine, and you have a portable AI workstation.

```
sudo apt install live-build curl gnupg grub-pc-bin xorriso
sudo ./build.sh
sudo ./flash.sh /dev/sdX
```

Replace `/dev/sdX`

with your USB device (`lsblk`

to find it). The script writes the ISO and creates the persistence partition automatically — the USB is ready to use from the first boot.

## Manual flash (without persistence)

```
sudo umount /dev/sdX*
sudo dd if=live-image-amd64.hybrid.iso of=/dev/sdX bs=4M status=progress
```

If you flash manually, the persistence partition will be created automatically on first boot instead.

Log in with `claudios`

/ `claudios`

and you're in Claude Code.

```
BIOS/UEFI → GRUB → Linux → TTY login
  └─ user: claudios / password: claudios
       └─ claudios-shell (login shell)
            ├─ [if claude missing] auto-install via npm
            └─ Claude Code in loop
                 └─ Ctrl+C (3s) → escape to bash
```

`claudios-shell`

is the user's actual login shell — set in `/etc/passwd`

, not a `.bashrc`

hack. It launches Claude Code in a loop. If Claude exits, you're prompted to restart or drop to bash.

**Zero-config boot**— log in and you're in Claude Code, ready to work** USB persistence**— first boot auto-creates a persistence partition; your auth, config, and session history survive reboots** Escape hatch**— hold Ctrl+C for 3 seconds at startup to drop to a standard bash shell** Auto-install**— if`claude`

isn't found in PATH, it's installed automatically via npm**Built-in slash commands**—`/reboot`

reboots the system,`/shut-down`

exits back to the shell**Passwordless sudo**— for system operations Claude needs (reboot, package install)**~1 GB ISO**— boots in under a minute on most hardware

No need to flash a USB to try it:

```
sudo apt install qemu-system-x86
./test.sh
```

Already flashed a USB? You can boot it in QEMU too:

```
sudo qemu-system-x86_64 \
  -drive file=/dev/sdX,format=raw \
  -m 4G \
  -enable-kvm \
  -cpu host \
  -device virtio-vga \
  -display gtk
```

Replace `/dev/sdX`

with your USB device (`lsblk`

to find it). The ISO boots in BIOS/Legacy mode.

Tip:To log in to your Claude account from your PC terminal (so you can copy and paste the auth URL easily), boot with`-nographic`

instead:

```
sudo qemu-system-x86_64 \
  -drive file=/dev/sda,format=raw \
  -m 4G \
  -enable-kvm \
  -cpu host \
  -nographic \
  -serial mon:stdio
```

- Linux system with
`live-build`

`curl`

,`gnupg`

,`grub-pc-bin`

,`xorriso`

- Internet connection
- ~10 GB free disk space

`auto/config`

— passes flags to`lb config`

(Ubuntu Noble, amd64, GRUB bootloader)`config/package-lists/claudios.list.chroot`

— packages installed in the image`config/hooks/live/*.hook.chroot`

— chroot scripts (locale, Node.js, Claude Code, user creation)`config/includes.chroot/`

— files copied verbatim into the filesystem

```
sudo ./clean.sh
```

To also remove the package cache (forces a full re-download on next build):

```
sudo ./clean.sh && sudo rm -rf cache/
claudios/
├── build.sh                    # Main build script (requires sudo)
├── flash.sh                    # Flashes ISO to USB with persistence
├── clean.sh                    # Removes build artifacts
├── test.sh                     # Launches the ISO in QEMU
├── auto/
│   ├── config                  # live-build configuration
│   ├── build                   # Wrapper for lb build
│   └── clean                   # Wrapper for lb clean
└── config/
    ├── archives/               # Additional apt repositories (NodeSource)
    ├── package-lists/          # Packages to install in the ISO
    ├── hooks/live/             # Scripts that run inside the build chroot
    │   ├── 0050-locale-timezone.hook.chroot
    │   ├── 0100-install-nodejs.hook.chroot
    │   ├── 0200-install-claude-code.hook.chroot
    │   ├── 0300-create-user.hook.chroot
    │   └── 0350-enable-persist.hook.chroot
    └── includes.chroot/        # Files copied directly into the filesystem
        ├── etc/motd
        ├── etc/shells
        ├── etc/sudoers.d/claudios
        ├── etc/systemd/system/
        │   └── claudios-persist.service
        ├── home/claudios/.claude/commands/
        │   ├── reboot.md            # /reboot slash command
        │   └── shut-down.md        # /shut-down slash command
        └── usr/local/bin/
            ├── claudios-shell      # Primary login shell
            └── claudios-persist    # Auto-persistence setup script
```

If `claudios-shell`

fails and you lose access:

**From GRUB**: edit the kernel line and append`init=/bin/bash`

**From TTY**: the`claudios`

user has sudo — use`chsh`

to change the shell

| Field | Value |
|---|---|
| Username | `claudios` |
| Password | `claudios` |
| API key | managed by Claude Code |