← Projects

claude-os

A Debian 13 appliance. btrfs snapshots as undo, reinstall in twenty minutes.

Shell
Star on GitHub Everything below is served from here: main at a2a3cff, taken 14 August 2026
Download the USB installer
Bootable ISO · claude-os-13.6.0-amd64.iso · 754.3 MB · Debian 13.6.0 + a2a3cff sha256 a19ed089dccd7ce37475ecb63bad2783e4f951592f4e1af7523ec7e352f40559

Write it to a USB stick, boot the machine from it, and it installs itself.

This formats the partition you point it at and everything on that partition goes. It installs a headless machine on which an agent runs as root. It is for a spare computer, not the one you use.

How to install
Write it to a stick, on Windows

Use Rufus. Pick the ISO, pick the stick, leave the mode at ISO Image, press Start. Anything already on the stick goes.

On macOS

Find the stick, unmount it, then write. Check the number twice: the wrong one overwrites the wrong disk.

diskutil list
diskutil unmountDisk /dev/diskN
sudo dd if=claude-os-13.6.0-amd64.iso of=/dev/rdiskN bs=4m
On Linux

GNOME Disks, choose the stick, Restore Disk Image, pick the ISO. Or, checking the letter twice:

sudo dd if=claude-os-13.6.0-amd64.iso of=/dev/sdX bs=4M status=progress oflag=sync
First boot

Boot the machine from the stick. BIOS and UEFI both work. Install Claude OS is the first entry and the one the countdown lands on. Every question is answered already except two: your password, and partitioning.

Partitioning is the careful part

Choose Manual. Format only the partition you mean to give it, as btrfs, mounted at /. Leave the EFI partition alone and do not tick format on it, or nothing else on the machine boots. The confirmation screen lists exactly what will be formatted, and reading that screen is the whole safeguard.

After it reboots

Log in and run the bootstrap. It reshapes the filesystem and asks for a reboot; run it again after that and it finishes in about fifteen minutes.

sudo /opt/claude-os/bootstrap.sh
sudo reboot
sudo /opt/claude-os/bootstrap.sh
sudo /opt/claude-os/doctor.sh
Stars0
Files45
Code80 kB
Snapshot2026-08-14
Shell 48.5%Markdown 31.7%Other 17.2%JavaScript 1.9%JSON 0.7%

Claude OS

A Debian 13 configuration for running Claude Code on bare metal: a headless appliance where the agent has root, and safety comes from btrfs snapshots and a fast reinstall rather than permission prompts.

Built for a Dell Inspiron 7548 on the LAN (claude-os.local), lid closed, reached over SSH. It replaces a Zorin partition and leaves Windows bootable.

What it optimises for

Inference latency is the bottleneck, not the OS. In order:

  1. Nothing may cost the agent a turn: no interactive prompts, no pagers, no

missing tools, no conffile questions.

  1. Every byte of stdout costs context: no colour, no progress bars, no MOTD, a

two-character prompt.

  1. The agent runs as root. Undo is snap rollback, the fallback is a bootable

snapshot in the GRUB menu, and the last resort is a 20-minute reinstall.

Debian, bash and apt throughout, on the grounds that they are the best represented in an LLM's training data.

Quickstart

# 1. Install Debian 13 netinst with preseed.cfg  -> docs/INSTALL.md
# 2. First boot:
sudo /opt/claude-os/bootstrap.sh     # reshapes btrfs, says "reboot"
sudo reboot
sudo /opt/claude-os/bootstrap.sh     # installs everything else
# 3. Paste SSH keys: authenticate claude          -> docs/INSTALL.md §6-7
sudo /opt/claude-os/doctor.sh        # every line should say OK

bootstrap.sh is idempotent. Run it after any repo change. doctor.sh is the acceptance test.

Layout

PathWhat
bootstrap.shentry point; clones or updates the repo, runs stages in order
stages/10..80idempotent build stages: base, fs, env, toolchain, claude, sensor, appliance, docker
config/every deployed file, in the repo rather than in heredocs
doctor.shverifies the spec, OK/FAIL/SKIP per line
docs/INSTALL.mdUSB to netinst to first boot
docs/ROLLBACK.mdsnapshot rollback, boot into snapshot, full reinstall
docs/DESIGN.mdwhy each decision was made
test/chroot-test.shbootstrap and doctor in a fresh trixie chroot

Safety model

snapper snapshots the root subvolume, and a PreToolUse hook takes one before mutating commands, rate-limited. grub-btrfs makes every snapshot bootable from the GRUB menu. The snap CLI wraps now, list, diff, rollback and prune.

/home and /var/log are separate subvolumes, so rolling back the OS does not take work or logs with it. Failing all of that, a netinst USB with preseed.cfg and bootstrap.sh rebuilds the machine in about 20 minutes.