CoLinux Lite

A bootable Linux appliance whose main interface is Codex CLI.
Plug in a USB, boot it, and talk to your machines.

Features • Editions • For Humans • For AI Agents • Quick Start • Build • Install • Disk Safety • Security • Release • License

What is CoLinux Lite?

CoLinux Lite is a minimal, bootable Linux distribution built on Alpine Linux that boots directly into OpenAI Codex CLI. There's no desktop environment to configure, no package manager to wrestle with — just a terminal with an AI coding agent that has the tools to inspect disks, recover files, diagnose systems, and automate infrastructure, all through natural language.

Think of it as a rescue USB for the AI age.

Boot from USB on any x86_64 PC — no installation required.
Talk to Codex immediately after boot — it's the only UI.
Safe disk access by default: everything mounts read-only, writes require explicit multi-step confirmation.
Encrypted persistence via LUKS — your Codex sessions, logs, and configuration survive reboots.
~120 MB base image — fits on any USB drive, boots in seconds.

CoLinux Lite is not a general-purpose Linux distribution. It's a purpose-built appliance for AI-assisted system administration, data recovery, and infrastructure automation.

Features

⚡ Fast boot — Alpine Linux + busybox init gets you to a shell in under 10 seconds.
🛡️ Safe disk control — all block devices mount read-only by default; writes require interactive confirmation with a typed safety phrase.
🔒 Encrypted persistence — optional LUKS partition stores Codex config, history, and custom tools across reboots.
📦 Minimal footprint — ~120 MB compressed base image, ~300 MB uncompressed.
🔧 Disk tools pre-installed — lsblk, parted, fdisk, fsck, testdisk, ntfs-3g, ext4/dosfstools, cryptsetup, mdadm.
🤖 Codex CLI integration — OpenAI Codex CLI runs as the primary interface with pre-configured safe wrappers.
📋 codexctl — a control surface for managing Codex sessions, disk state, and appliance configuration.
🖥️ Multiple editions — choose from headless TTY, GUI (cage/sway), or Debian-based compat builds.
🔍 Forensic mode — block-level imaging with write-protect guarantees and SHA-256 verification.
🔄 Auto-updates — periodic Codex CLI version checks via cron with configurable channels.
📝 Comprehensive logging — all disk operations, Codex commands, and system events logged to /persist/logs/.
🗃️ File recovery — recover deleted files from any filesystem using testdisk/photorec (codex-recover).
📀 Disk cloning — resilient disk/partition cloning with ddrescue and SHA-256 verification (codex-clone).
🌐 Remote access — SSH key management, Cloudflare tunnels, and QR code sharing (codex-remote).
📸 State snapshots — portable snapshots with metadata for easy transfer and restore (codex-snapshot).
🩺 Hardware diagnostics — RAM, SMART disk health, CPU temperature, battery info (codex-hw-check).
⏱️ Benchmarks — quick CPU crypto, disk I/O, and network speed tests (codex-benchmark).
🖧 Network boot (PXE) — boot CoLinux on other machines over the network, no USB needed (codex-pxe).

Screenshots

📷 Screenshots coming soon.

Boot screen	Codex CLI session	Disk inspection
(placeholder)	(placeholder)	(placeholder)

Editions

CoLinux Lite ships in multiple editions for different use cases:

Edition	Base	UI	Target	Status
`colinux-lite`	Alpine Linux	TTY (agetty)	USB sticks, headless machines	✅ Stable
`colinux-lite-gui`	Alpine Linux	cage + sway + foot	Machines with display output	🧪 Experimental
`colinux-compat`	Debian minimal	TTY (agetty)	Hardware incompatible with Alpine	🧪 Experimental
`colinux-desktop`	Alpine Linux	GNOME + Electron Codex	Full desktop experience	📋 Planned

See docs/EDITIONS.md for a detailed comparison.

Quick Start

1. Build the ISO

# Using Docker (works on any host):
git clone https://github.com/gibavargas/colinux.git
cd colinux
docker run --rm -v "$(pwd):/src" -e ARCH=x86_64 -e OUTDIR=/src/dist \
  alpine:3.21 sh -c "apk add --no-cache alpine-sdk apk-tools alpine-conf bash curl \
  ca-certificates git xorriso squashfs-tools mtools dosfstools grub grub-efi \
  efibootmgr e2fsprogs qemu-img openssl && cd /src && bash scripts/build-alpine.sh"

Or on an Alpine Linux host: sudo bash scripts/build-alpine.sh --arch x86_64

2. Smoke-test with QEMU

# Automated smoke tests (build → codexctl + QEMU boot + disk inventory):
./scripts/smoke-test.sh --all

# Or run stages individually:
./scripts/smoke-test.sh --docker                   # Docker build + codexctl validate
./scripts/smoke-test.sh --iso                      # QEMU boot test (auto-finds ISO)
./scripts/smoke-test.sh --first-boot               # Simulate first-boot hook execution in Docker

# Boot interactively in QEMU:
./scripts/build-qemu.sh --iso dist/colinux-lite-x86_64-*.iso --boot --no-gui

3. Write to a USB drive

sudo dd if=dist/colinux-lite-x86_64-*.iso of=/dev/sdX bs=4M status=progress && sync

⚠️ Replace /dev/sdX with your actual USB device. This will erase all data on the target drive.

4. Boot it

Insert the USB, boot from it, and you'll be dropped into a Codex CLI session. Start typing.

Requirements

To build

Build host: Alpine Linux 3.19+ (recommended) or Docker with Alpine container
Disk space: ~2 GB for build artifacts
Tools: apk-tools, mkinitfs, syslinux, xorriso, mksquashfs, cryptsetup
Optional: QEMU for testing (qemu-system-x86_64)

To run

x86_64 PC with USB boot support (UEFI or legacy BIOS)
RAM: 2 GB minimum, 4 GB recommended
Storage: 4 GB+ USB drive (8 GB recommended for persistence)
Network: Internet access required for Codex CLI (OpenAI API key)

Project Structure

colinux/
├── README.md                          # This file
├── LICENSE                            # GPLv2 License
├── .github/workflows/                 # CI/CD (Docker, Alpine ISO, Debian ISO, release)
├── profiles/
│   ├── alpine/                        # colinux-lite, colinux-lite-gui, colinux-desktop
│   │   ├── packages.x86_64           # Alpine packages (x86_64)
│   │   ├── packages.aarch64          # Alpine packages (aarch64)
│   │   ├── overlay/                   # Headless TTY overlay
│   │   │   ├── etc/
│   │   │   │   ├── init.d/            # OpenRC init scripts
│   │   │   │   │   ├── codex-firstboot
│   │   │   │   │   ├── codex-auto-update
│   │   │   │   │   └── ...
│   │   │   │   ├── doas.conf          # doas privilege rules
│   │   │   │   └── codex-update-crontab
│   │   │   └── usr/local/bin/         # codex-* command wrappers
│   │   │       ├── codexctl           # Codex control surface
│   │   │       ├── codex-backup       # Workspace persistence backups
│   │   │       ├── codex-restore      # Restore from backups
│   │   │       ├── codex-disk-inventory # Disk inventory (JSON + Markdown)
│   │   │       ├── codex-mount-ro / codex-mount-rw # Safe mount wrappers
│   │   │       ├── codex-network      # Network configuration
│   │   │       ├── codex-update       # Codex CLI updater
│   │   │       ├── codex-shell        # Safe shell escalation
│   │   │       ├── codex-install-usb / codex-install-pc # Installers
│   │   │       └── ...                # (16 more codex-* commands)
│   │   ├── overlay-gui/              # GUI (cage/sway) additions
│   │   └── overlay-desktop/          # Desktop (GNOME) additions
│   ├── debian/                        # Debian desktop profile
│   └── debian-compat/                 # Debian compat (minimal) profile
├── shared/                            # Shared infra (Camoufox, WiFi wizard, network)
├── scripts/
│   ├── build-alpine.sh                # Alpine ISO build (lite)
│   ├── build-alpine-gui.sh            # Alpine ISO build (GUI)
│   ├── build-alpine-desktop.sh        # Alpine ISO build (desktop)
│   ├── build-debian-compat.sh         # Debian compat ISO build
│   ├── build-debian.sh                # Debian desktop ISO build
│   ├── smoke-test.sh               # Unified smoke test (Docker + ISO)
│   ├── test-iso.sh                    # QEMU ISO boot test (detailed)
│   ├── build-qemu.sh                  # QEMU interactive boot
│   ├── first-boot.sh                  # First-boot setup
│   └── setup-codex.sh                # Codex CLI setup/update
├── installer/                         # Canonical installer scripts
├── docs/
│   ├── BUILD.md                       # Build instructions
│   ├── SECURITY.md                    # Security documentation
│   ├── DISK_SAFETY.md                 # Disk safety model
│   ├── EDITIONS.md                    # Edition comparison
│   ├── RELEASE.md                     # v0.2 release checklist & MVP exit criteria
│   └── GUIDE_DESKTOP.md               # Desktop edition guide
└── AGENTS.md                          # Codex agent operating rules

Building from Source

See docs/BUILD.md for the full build guide. Quick summary:

# Clone the repository
git clone https://github.com/gibavargas/colinux.git
cd colinux

# Build the lite ISO (Docker, any host)
docker run --rm -v "$(pwd):/src" -e ARCH=x86_64 -e OUTDIR=/src/dist \
  alpine:3.21 sh -c "apk add --no-cache alpine-sdk apk-tools alpine-conf bash curl \
  ca-certificates git xorriso squashfs-tools mtools dosfstools grub grub-efi \
  efibootmgr e2fsprogs qemu-img openssl && cd /src && bash scripts/build-alpine.sh"

# Or on Alpine Linux host
sudo bash scripts/build-alpine.sh --arch x86_64

Build configuration

Set environment variables to override defaults:

Variable	Default	Description
`ARCH`	`x86_64`	Target architecture (`x86_64` or `aarch64`)
`CODEX_VERSION`	`latest`	Codex CLI version to bundle
`ALPINE_RELEASE`	`3.21`	Alpine version
`OUTDIR`	`./dist`	Output directory

Releasing

To cut a v0.2 (or later) release — build artifacts, generate checksums + manifest, sign, and publish — follow the checklist in docs/RELEASE.md. It covers MVP exit criteria, pre-release checks, artifact generation with scripts/release.sh, and post-release verification.

Installation

USB Drive (Live)

# Identify your USB drive
lsblk

# Write the image
sudo dd if=dist/colinux-lite-x86_64-*.iso of=/dev/sdX bs=4M status=progress && sync

USB Installation

Use codex-install-usb from a running CoLinux session:

doas codex-install-usb /dev/sdX

PC Installation

Use codex-install-pc to install CoLinux to an internal disk:

# Simulate first (no disk changes):
doas codex-install-pc /dev/nvme0n1 --dry-run

# Install for real:
doas codex-install-pc /dev/nvme0n1          # full disk
doas codex-install-pc /dev/sda --dual-boot  # dual-boot with existing OS

Persistence

CoLinux runs as a live appliance. To persist data across reboots:

Boot from the USB drive.
Run doas codex-usb-persist /dev/sdX to create an encrypted persistence partition.
Your Codex config, session history, and logs will persist across reboots.

🔒 Persistence uses LUKS2 with AES-256-XTS. You'll set a passphrase on first setup.

First Boot Experience

When you boot CoLinux Lite for the first time:

Bootloader — syslinux presents a brief boot menu (Live, Forensic, Debug).
Kernel + initramfs — boots into Alpine's initramfs, loads modules.
Overlay mount — the squashfs root filesystem is mounted read-only; an overlayfs tmpfs provides writable space.
First-boot script — if /persist/.first-boot-done doesn't exist:
- Generates machine ID and host keys.
- Initializes /persist/ directory structure.
- Prompts for OpenAI API key (stored in encrypted persistence).
- Configures Codex CLI with safe defaults.
- Sets up the cron auto-update job.
- Creates the flag file.
Codex CLI — you're dropped into a Codex session. Start typing commands.

Subsequent boots skip the first-boot wizard and go straight to Codex.

Disk Safety Model

CoLinux Lite treats every disk as potentially valuable and dangerous by default.

Operation	Default	Escalation
List devices	✅ Allowed	None
Read files	✅ Allowed (read-only mount)	None
Mount filesystem	⚠️ Read-only	Explicit write mount
Write/modify files	❌ Blocked	Multi-step confirmation
Format/partition	❌ Blocked	Multi-step + typed safety phrase
Block-level write (dd)	❌ Blocked	Multi-step + typed safety phrase + timeout
Boot device operations	❌ Always blocked	Cannot be escalated

See docs/DISK_SAFETY.md for the complete specification.

Codex Control Surface (`codexctl`)

codexctl is the appliance management CLI:

# Check system status
codexctl status

# List detected disks
codexctl disks

# Mount a disk read-only
codexctl mount /dev/sdb1 /mnt/target

# Request write access (triggers interactive confirmation)
codexctl mount --write /dev/sdb1 /mnt/target

# Enter forensic mode (all disks read-only, immutable)
codexctl forensic on

# Create a disk image with verification
codexctl image /dev/sdb --output /persist/images/sdb.img

# Manage persistence
codexctl persistence setup /dev/sdc
codexctl persistence status

# Update Codex CLI
codexctl update --channel stable

🧑 For Humans

Prerequisites

To use CoLinux Lite, you need:

A USB drive — 4 GB minimum, 8 GB+ recommended (for persistence)
An x86_64 PC with USB boot support (UEFI or legacy BIOS)
2 GB RAM minimum (4 GB recommended)
Internet access — required for OpenAI Codex CLI to function
An OpenAI API key — you'll be prompted for it on first boot

To build from source, you also need:

Docker (easiest) or an Alpine Linux 3.19+ host
~2 GB of free disk space

Quick Start — Docker Validate

# Build and validate the Docker environment (syntax + deps + codexctl)
./scripts/smoke-test.sh --docker

Quick Start — Full ISO Build

# Build the Alpine ISO in a Docker container
docker run --rm -v "$(pwd):/src" -e ARCH=x86_64 -e OUTDIR=/src/dist \
  alpine:3.21 sh -c "apk add --no-cache alpine-sdk apk-tools alpine-conf bash curl \
  ca-certificates git xorriso squashfs-tools mtools dosfstools grub grub-efi \
  efibootmgr e2fsprogs qemu-img openssl && cd /src && bash scripts/build-alpine.sh"

# Smoke-test the ISO with QEMU
./scripts/smoke-test.sh --iso

# Or the full pipeline (Docker validate + ISO boot):
# ./scripts/smoke-test.sh --all

Creating a Bootable USB

Option A: dd (Linux/macOS)

# Find your USB drive
lsblk

# Write the image (REPLACE /dev/sdX WITH YOUR DEVICE)
sudo dd if=dist/colinux-lite-x86_64-*.iso of=/dev/sdX bs=4M status=progress && sync

⚠️ This will erase all data on the target drive. Double-check the device name.

Option B: balenaEtcher (Windows/macOS/Linux)

Download balenaEtcher
Select the ISO file
Select your USB drive
Click "Flash"

First Boot Walkthrough

When you boot CoLinux Lite for the first time, here's what happens:

Bootloader menu — syslinux shows three options:
- Live — normal boot (choose this)
- Forensic — all disks forced read-only
- Debug — verbose boot with shell fallback
Kernel loads — Alpine's initramfs boots in under 10 seconds

First-boot wizard runs automatically:

=== CoLinux Lite — First Boot Setup ===
? Enter your OpenAI API key: sk-...
✓ Codex CLI configured
? Set up encrypted persistence? (y/N):

Codex CLI launches — you see the Codex prompt:
```
codex> 
```

Start typing. For example:

codex> Show me what disks are attached
codex> List all files on the second partition of /dev/sdb
codex> What's the SMART health status of /dev/sda?

Subsequent boots skip the wizard and go straight to Codex.

Using Codex (Basic Commands)

Codex CLI is a natural language interface. Here are things you can ask:

# System information
codex> What OS version are we running? What kernel?
codex> How much RAM and disk space is available?

# File operations
codex> List all files in /mnt/disks/by-device/sdb1
codex> Copy the photos folder from the USB drive to /persist/data/
codex> Find all .jpg files larger than 5MB on the mounted drive

# Disk operations
codex> Show me all attached block devices with their filesystems
codex> What's the partition table of /dev/nvme0n1?
codex> Check the filesystem health of /dev/sda1

# Recovery
codex> I accidentally deleted a file called report.docx — can you recover it?
codex> This NTFS drive won't mount, help me diagnose it

# Networking
codex> Scan the local network for devices
codex> Test if I can reach the internet

Disk Operations

All disk operations go through codexctl for safety:

# See what's attached
codexctl disks

# Mount a drive read-only (safe, always allowed)
codexctl mount-ro /dev/sdb1
ls /mnt/disks/by-device/sdb1/

# Mount read-write (requires confirmation with device serial)
codexctl mount-rw --confirm "WD-WMC4T0123456" /dev/sdb1

# Copy files from a mounted drive to persistent storage
cp -r /mnt/disks/by-device/sdb1/photos /persist/data/

# Create a forensic disk image (with SHA-256 verification)
codexctl image /dev/sdb --output /persist/images/evidence.img

# Enter forensic mode (all operations read-only, immutable)
codexctl forensic on

# View mounted disks
mount | grep /mnt/disks

Network Setup

# Check current network status
codexctl network

# Wired: usually auto-configured via DHCP
# If not, bring up the interface:
codexctl network up eth0

# Wireless: scan and connect
codexctl network scan
codexctl network connect "MyWiFi" "password123"

# Check connectivity
ping -c 3 8.8.8.8
curl -sS ifconfig.me

Troubleshooting Common Issues

Problem	Solution
Won't boot from USB	Check BIOS/UEFI boot order; try "USB HDD" or "UEFI: "
Black screen after boot	Reboot and select `Debug` from the boot menu; check graphics compatibility
No network	Run `codexctl network`; try `ip link` to see interfaces; check cable/WiFi
Codex says "API key invalid"	Run `setup-codex --key` to reconfigure your OpenAI API key
Can't write to USB drive	By design! Use `codexctl mount-rw --confirm <SERIAL> <device>`
Disk won't mount	Try `codexctl mount-ro /dev/sdXN` first; run `fsck /dev/sdXN` to check
Out of space on persistence	Run `df -h /persist`; clean up with `codexctl backup --list`
Slow boot	Check USB drive speed (USB 3.0+ recommended); try a different port

FAQ

Q: Does CoLinux install anything on my computer? A: No. It runs entirely from the USB drive. Nothing is written to your internal disks unless you explicitly request it.

Q: Can I use it without an OpenAI API key? A: You can use the shell and disk tools without an API key, but the Codex AI assistant requires one.

Q: How do I update Codex CLI? A: Run codexctl update — it checks for new versions and updates automatically.

Q: Can I run this in a virtual machine? A: Yes. qemu-system-x86_64 -m 2048 -cdrom dist/colinux-lite-x86_64-*.iso -boot d or use VirtualBox/VMware.

Q: How do I set up persistence? A: Run codexctl persist setup /dev/sdX during a live session. It creates an encrypted partition for your config, logs, and data.

Q: Is my API key stored securely? A: Yes. API keys are stored in /persist/config/ with 0600 permissions, owned by the codex user. If using LUKS persistence, the key is encrypted on disk.

🤖 For AI Agents

AGENTS.md — The Rules Codex Follows

CoLinux places an AGENTS.md file at /workspace/AGENTS.md on first boot. This file contains all operating rules that Codex must follow. Key rules:

Disk Safety — Never write to disks without explicit user confirmation. Always run codex-disk-inventory first.
Read-First — Mount unknown filesystems read-only before any write operations.
Persistence Layout — Use /persist/ for all persistent data (config/, data/, logs/, backups/).
Network — Use codex-network for all network operations. Prefer wired over wireless.
Logging — All operations must be logged to /persist/logs/ in format YYYY-MM-DD HH:MM:SS [LEVEL] message.
Security — Only codex-* commands are whitelisted in doas.conf. Never escalate outside these.
Workspace — /workspace is ephemeral. Persistent data goes to /workspace/data (bind-mounted from /persist/data/).

See the full AGENTS.md in the repository root.

codexctl API Reference

codexctl is the primary control interface. All subcommands:

# System info
codexctl status                 # Human-readable status
codexctl status --json          # JSON output for programmatic use

# Version info
codexctl version                # Show CoLinux + Codex CLI versions

# Disk operations
codexctl disks                  # Disk inventory (human)
codexctl disks --json           # Disk inventory (JSON)

# Mounting
codexctl mount-ro /dev/sdb1     # Read-only mount (always safe)
codexctl mount-rw --confirm "SERIAL" /dev/sdb1 /mnt/target  # Read-write (requires confirmation)

# Persistence
codexctl persist                # Show persistence status
codexctl persist open /dev/sdX3 # Unlock LUKS persistence
codexctl persist close          # Lock persistence

# Updates
codexctl update                 # Update Codex CLI + Alpine packages
codexctl update --check         # Check for available updates

# Network
codexctl network                # Network status
codexctl network up eth0        # Bring up interface
codexctl network scan           # Scan WiFi networks

# Logs
codexctl logs                   # View system logs
codexctl logs --follow          # Tail logs

# Backups
codexctl backup                 # Create workspace backup
codexctl backup --list          # List existing backups

# Installation
codexctl install-usb /dev/sdX   # Install CoLinux to USB
codexctl install-pc             # Install to internal disk

codex-* Command Reference

Beyond codexctl, CoLinux provides specialized command-line tools for specific tasks:

Recovery & Cloning

# File recovery — scan for and recover deleted files
codex-recover --scan /dev/sdb1              # Quick filesystem scan
codex-recover --deep /dev/sdb1              # Deep file carving (slower)
codex-recover --deep /dev/sdb1 --type jpg,pdf  # Recover specific file types
codex-recover --list                        # List devices available for recovery

# Disk cloning — resilient copy with ddrescue
codex-clone /dev/sda /dev/sdb               # Clone entire disk
codex-clone /dev/sda1 /mnt/usb/backup.img   # Partition to image file
codex-clone --verify /mnt/backup.img /dev/sda1  # Verify image integrity
codex-clone --status                        # Show active clone sessions

Remote Access

codex-remote --ssh                          # Show SSH connection info
codex-remote --ssh-key                      # Generate new SSH key pair
codex-remote --tunnel localhost:22           # Create Cloudflare tunnel
codex-remote --qr                           # Show connection QR code
codex-remote --status                       # Show remote access status

Snapshots & Backups

codex-snapshot                              # Create timestamped snapshot with metadata
codex-snapshot --list                       # List snapshots with metadata
codex-snapshot --restore colinux-hostname-20250101.tar.gz  # Restore a snapshot
codex-snapshot --upload https://example.com/backups/  # Upload to remote server
codex-snapshot --prune 5                    # Keep only last 5 snapshots

Diagnostics & Benchmarks

# Hardware diagnostics
codex-hw-check                              # Full diagnostics (RAM, disks, CPU, battery)
codex-hw-check --quick                      # Quick summary only
codex-hw-check --smart /dev/sda             # Detailed SMART data for a device
codex-hw-check --json                       # JSON output

# Quick benchmarks
codex-benchmark                             # Run all (CPU + disk + network)
codex-benchmark --cpu                       # CPU crypto only (AES, SHA, RSA)
codex-benchmark --disk /persist             # Disk I/O on specific target
codex-benchmark --network                   # Download speed + latency
codex-benchmark --json                      # JSON output

Network Boot (PXE)

codex-pxe --start                           # Start PXE server on default interface
codex-pxe --start eth1                      # Start on specific interface
codex-pxe --start --iso /path/to/colinux.iso  # Extract from ISO and start
codex-pxe --status                          # Show server status + connected clients
codex-pxe --stop                            # Stop PXE server

💡 PXE boot flow: The host machine runs codex-pxe --start --iso colinux.iso. Any other PC on the same network boots via F12/Network Boot and loads CoLinux entirely over the network — no USB required. Perfect for remote assistance scenarios.

Programmatic Disk Operations (JSON Output)

For CI/CD and automation, use --json flags:

# Get system status as JSON
codexctl status --json
# Output:
# {
#   "colinux_version": "0.1.0",
#   "codex_cli": "codex 0.1.0",
#   "kernel": "6.6.x",
#   "arch": "x86_64",
#   "hostname": "colinux",
#   "uptime": "up 5 minutes",
#   "timestamp": "2025-01-15T10:30:00Z"
# }

# Get disk inventory as JSON
codexctl disks --json
# Output:
# {
#   "devices": [
#     {
#       "name": "/dev/sda",
#       "serial": "WD-WMC4T0123456",
#       "size": "500107862016",
#       "model": "WDC WD5000LPCX",
#       "partitions": [...],
#       "safety": "foreign_disk"
#     }
#   ]
# }

# Parse with jq
codexctl disks --json | jq '.devices[] | {name, size, safety}'
codexctl status --json | jq '.codex_cli'

Building Custom Images Programmatically

Docker build (recommended for CI):

# Build with a specific Codex version
docker build \
  --build-arg CODEX_VERSION=0.1.0 \
  -t colinux-lite:custom .

# Run with persistent volume
docker run -it \
  -v ./my-data:/workspace/data \
  -e OPENAI_API_KEY=sk-... \
  colinux-lite:custom

Alpine ISO build (in CI):

# Build for x86_64
ARCH=x86_64 ALPINE_RELEASE=3.21 OUTDIR=./dist \
  bash scripts/build-alpine.sh

# Build for aarch64
ARCH=aarch64 ALPINE_RELEASE=3.21 OUTDIR=./dist \
  bash scripts/build-alpine.sh

# With specific Codex version
CODEX_VERSION=v0.1.0 ARCH=x86_64 bash scripts/build-alpine.sh

Testing in CI/CD

# Quick Docker validation (build + codexctl + syntax + doas check)
./scripts/smoke-test.sh --docker

# QEMU boot test (requires a built ISO)
./scripts/smoke-test.sh --iso

# First-boot hook simulation (runs in Docker, no real disk/network)
./scripts/smoke-test.sh --first-boot

# Full pipeline
./scripts/smoke-test.sh --all

# Manual QEMU boot for interactive testing
./scripts/build-qemu.sh --iso dist/colinux-lite-x86_64-*.iso --boot --no-gui

Integration Patterns

Pattern 1: Automated data recovery pipeline

# Boot CoLinux, mount evidence drive, image it, hash it
codexctl mount-ro /dev/sdb1
codexctl image /dev/sdb --output /persist/images/evidence-$(date +%Y%m%d).img
sha256sum /persist/images/evidence-*.img > /persist/images/evidence.sha256

Pattern 2: CI/CD infrastructure tool

# Use CoLinux in Docker as a Codex agent for infrastructure tasks
docker run -it --rm \
  -v ~/.ssh:/persist/ssh:ro \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  colinux-lite \
  codex -q "Check the health of all disks on these servers: host1, host2, host3"

Pattern 3: Batch processing with JSON output

# Script: inventory-all-disks.sh
#!/bin/bash
codexctl disks --json | jq -r '.devices[].name' | while read dev; do
  echo "=== $dev ==="
  codexctl mount-ro "$dev" 2>/dev/null || continue
  echo "Mounted successfully"
  codexctl persist
done

Pattern 4: Custom AGENTS.md for your workflow

# Mount your custom rules
docker run -it --rm \
  -v ./my-agents.md:/workspace/AGENTS.md \
  -v ./scripts:/workspace/custom-tools \
  colinux-lite

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository and create a feature branch.
Test your changes — run ./scripts/smoke-test.sh --docker and verify with QEMU if applicable.
Document — update docs for any behavioral changes.
Keep it minimal — this is a tiny appliance. Every byte counts. Justify new dependencies.
Respect the safety model — never bypass disk safety checks without explicit, documented rationale.
Submit a PR with a clear description of what changed and why.

Code style

Shell scripts: follow Google Shell Style Guide.
Init scripts: follow OpenRC conventions (see existing scripts).
Python (if used): follow PEP 8 with flake8.

Reporting issues

Open a GitHub issue with:

CoLinux Lite edition and version.
Hardware description (PC model, USB drive).
Steps to reproduce.
Expected vs. actual behavior.
Relevant logs from /persist/logs/.

License

CoLinux Lite is released under the GNU General Public License v2.

Links

Codex CLI: github.com/openai/codex-cli
Alpine Linux: alpinelinux.org
OpenRC: github.com/OpenRC/openrc
LUKS: cryptsetup.gitlab.io

_{Built with ❤️ by the CoLinux Project}

Name		Name	Last commit message	Last commit date
Latest commit History 112 Commits
.github		.github
disk		disk
docs		docs
installer		installer
profiles		profiles
scripts		scripts
shared		shared
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
Dockerfile-compat		Dockerfile-compat
Dockerfile-desktop		Dockerfile-desktop
Dockerfile-gui		Dockerfile-gui
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

CoLinux Lite

What is CoLinux Lite?

Features

Screenshots

Editions

Quick Start

1. Build the ISO

2. Smoke-test with QEMU

3. Write to a USB drive

4. Boot it

Requirements

To build

To run

Project Structure

Building from Source

Build configuration

Releasing

Installation

USB Drive (Live)

USB Installation

PC Installation

Persistence

First Boot Experience

Disk Safety Model

Codex Control Surface (codexctl)

🧑 For Humans

Prerequisites

Quick Start — Docker Validate

Quick Start — Full ISO Build

Creating a Bootable USB

First Boot Walkthrough

Using Codex (Basic Commands)

Disk Operations

Network Setup

Troubleshooting Common Issues

FAQ

🤖 For AI Agents

AGENTS.md — The Rules Codex Follows

codexctl API Reference

codex-* Command Reference

Recovery & Cloning

Remote Access

Snapshots & Backups

Diagnostics & Benchmarks

Network Boot (PXE)

Programmatic Disk Operations (JSON Output)

Building Custom Images Programmatically

Testing in CI/CD

Integration Patterns

Contributing

Code style

Reporting issues

License

Links

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Codex Control Surface (`codexctl`)

Packages