Skip to content

Commit b967b96

Browse files
dddimchadddimcha
authored
feat: Add embodi CLI + fix macOS + clean README (#212)
* fix: macOS compatibility for grep in create_iso.sh - Replace grep -P (Perl regex) with portable awk extraction - Fixes ISO build script on macOS where grep -P is not available * docs: Rewrite README with clear step-by-step instructions - Add prerequisites for macOS, Ubuntu, and Arch - Add 3-command quick start (clone, build, run) - Add ISO build instructions with model download - Add USB write instructions for real hardware - Add interactive chat usage examples - Simplify and reorganize for better UX * feat: Add embodi CLI tool + clean README - Add ./embodi CLI with subcommands: build, iso, run, clean, test, help - Rewrite README with clear instructions (no emojis) - CLI examples: embodi iso --model models/smollm.gguf Usage: ./embodi build # Build kernel ./embodi iso --model X.gguf # Create ISO with model ./embodi run # Run in QEMU
1 parent aa035ff commit b967b96

3 files changed

Lines changed: 374 additions & 168 deletions

File tree

‎README.md‎

Lines changed: 149 additions & 159 deletions
Original file line numberDiff line numberDiff line change
@@ -1,202 +1,192 @@
11
# EMBODIOS - Bare-Metal AI Operating System
22

3-
[![Status](https://img.shields.io/badge/Status-95%25%20Complete-brightgreen)](https://github.com/dddimcha/embodiOS/wiki/Current-State-Analysis)
4-
[![AI Runtime](https://img.shields.io/badge/AI%20Runtime-100%25-brightgreen)](https://github.com/dddimcha/embodiOS/wiki/Pillar-1:-Ollama-GGUF-Integration)
5-
[![Drivers](https://img.shields.io/badge/Drivers-85%25-green)](https://github.com/dddimcha/embodiOS/wiki/Pillar-2:-Linux-Driver-Compatibility)
6-
[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
7-
[![Model Compatibility](https://img.shields.io/badge/Model%20Compatibility-CI-brightgreen)](https://github.com/dddimcha/embodiOS/actions/workflows/model-compatibility-ci.yml)
8-
9-
> **The world's first bare-metal AI operating system** - where the AI model runs directly on hardware as the OS kernel itself. No userspace. No OS overhead. Just transformers and hardware.
10-
11-
## What's New (January 2026)
12-
13-
- **Interactive Chat Mode:** `talk` command for dedicated conversation sessions with performance tracking
14-
- **Performance Stats:** Separate `perf` command to view timing metrics without cluttering chat
15-
- **Console UX:** Polished help system with categories, status display, command suggestions
16-
- **Production ISO Builder:** One-click bootable ISO with GRUB menu
17-
- **Stability Testing Suite:** Automated long-running tests (1h-72h) for memory leak detection
18-
- **Secure Boot:** UEFI Secure Boot support with signed kernel validation
19-
- **Streaming Inference:** Memory-efficient inference engine with parallel workers
20-
- **Industrial Protocols:** Modbus TCP and EtherCAT support for real-time automation
21-
22-
## Current Status
23-
24-
| Component | Status | Completion |
25-
|-----------|--------|------------|
26-
| **Kernel Foundation** | Memory, boot, interrupts, DMA, scheduler | 95% ✅ |
27-
| **AI Runtime** | GGUF, BPE, streaming inference, quantization | 100% ✅ |
28-
| **Drivers** | NVMe, VirtIO, e1000e, PCI, TCP/IP, Industrial | 85% ✅ |
29-
| **Performance** | SIMD, parallel inference, benchmarks | 90% ✅ |
30-
| **Documentation** | Wiki, README, Contributing guide | 100% ✅ |
31-
| **Overall** | **v1.0 Ready** - hardware testing only | **95%** |
3+
Run LLMs directly on hardware without any OS overhead. No Linux. No userspace. Just transformers and bare metal.
324

335
## Quick Start
346

35-
### Clone with Documentation
7+
### Prerequisites
368

9+
**macOS:**
3710
```bash
38-
# Clone with wiki submodule
39-
git clone --recurse-submodules https://github.com/dddimcha/embodiOS.git
40-
cd embodiOS
11+
brew install x86_64-elf-gcc x86_64-elf-binutils x86_64-elf-grub xorriso qemu
12+
```
13+
14+
**Ubuntu/Debian:**
15+
```bash
16+
sudo apt install gcc-x86-64-linux-gnu binutils-x86-64-linux-gnu grub-pc-bin xorriso qemu-system-x86
17+
```
4118

42-
# Or initialize submodule after clone
43-
git submodule update --init
19+
**Arch Linux:**
20+
```bash
21+
sudo pacman -S x86_64-elf-gcc x86_64-elf-binutils grub xorriso qemu
4422
```
4523

4624
### Build and Run
4725

4826
```bash
49-
# Build the kernel (requires Linux or Docker)
50-
cd kernel
51-
make
27+
git clone https://github.com/dddimcha/embodiOS.git
28+
cd embodiOS
29+
30+
./embodi build
31+
./embodi run
32+
```
5233

53-
# Run in QEMU
54-
qemu-system-x86_64 -kernel embodios.elf -m 256M -serial stdio
34+
## CLI Reference
35+
36+
```
37+
Usage: embodi <command> [options]
38+
39+
Commands:
40+
build Build the kernel
41+
iso Create bootable ISO
42+
run Run in QEMU
43+
clean Clean build artifacts
44+
test Run kernel tests
45+
help Show help
5546
```
5647

57-
### Chat with AI
48+
### Build Kernel
5849

5950
```bash
60-
> talk # Enter interactive chat mode (recommended!)
61-
You> Hello, how are you?
62-
AI> Hello! I'm doing well. How can I help you today?
63-
You> perf # Check performance inline
64-
[Session: 1 msgs, 15 tokens, 127 tok/s avg]
65-
You> exit # Leave chat mode
51+
./embodi build # Standard build
52+
./embodi build --debug # Debug build with symbols
53+
```
6654

67-
> chat Hello world # Single message (for scripting)
68-
> perf # View detailed performance stats
69-
> status # Check AI readiness
55+
### Create Bootable ISO
56+
57+
```bash
58+
./embodi iso # Without model
59+
./embodi iso --model models/smollm.gguf # With embedded model
60+
./embodi iso --model models/smollm.gguf --arch x86_64
7061
```
7162

72-
### System Commands
63+
### Run in QEMU
7364

7465
```bash
75-
> help # Show available commands
76-
> help ai # AI-specific commands
77-
> help all # All commands
78-
> benchmark # Full inference benchmark
79-
> mem # Show memory stats
80-
> lspci # List PCI devices
66+
./embodi run # Run kernel directly
67+
./embodi run --memory 2G # With more RAM
68+
./embodi run --iso # Boot from ISO
8169
```
8270

83-
See the **[Console Commands Reference](https://github.com/dddimcha/embodiOS/wiki/Console-Commands)** for all commands.
71+
### Download Models
72+
73+
```bash
74+
mkdir -p models
75+
76+
# SmolLM-135M (469MB, fast)
77+
curl -L -o models/smollm-135m.gguf \
78+
"https://huggingface.co/HuggingFaceTB/SmolLM-135M-Instruct-GGUF/resolve/main/smollm-135m-instruct-q6_k.gguf"
8479

85-
## Key Features
80+
# TinyLlama-1.1B (638MB, better quality)
81+
curl -L -o models/tinyllama-1.1b.gguf \
82+
"https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf"
83+
```
8684

87-
| Feature | Description |
85+
## Run on Real Hardware
86+
87+
### Write to USB
88+
89+
```bash
90+
# Build ISO with model
91+
./embodi iso --model models/smollm-135m.gguf
92+
93+
# Write to USB (replace /dev/sdX with your device)
94+
sudo dd if=build/embodios.iso of=/dev/sdX bs=4M status=progress conv=fsync
95+
```
96+
97+
### Boot
98+
99+
1. Insert USB into target machine
100+
2. Enter BIOS boot menu (F12, F2, or Del)
101+
3. Select USB device
102+
4. EMBODIOS boots to AI shell
103+
104+
## Shell Commands
105+
106+
Once booted:
107+
108+
| Command | Description |
88109
|---------|-------------|
89-
| **GGUF Model Support** | Load models from Ollama ecosystem directly |
90-
| **BPE Tokenization** | SentencePiece-compatible tokenizer from GGUF |
91-
| **Multi-Model** | Hot-swap between up to 8 loaded models |
92-
| **Integer-Only Math** | No FPU required - runs on any x86_64 |
93-
| **SIMD Acceleration** | SSE2/AVX2 for matrix operations |
94-
| **Zero-Copy DMA** | Identity-mapped memory for direct hardware access |
95-
| **UEFI Secure Boot** | Signed kernel validation for trusted boot chain |
96-
| **<1s Boot Time** | From power-on to AI inference ready |
97-
98-
## Architecture
99-
100-
```
101-
┌─────────────────────────────────────────────────────┐
102-
│ User Input │
103-
└─────────────────────┬───────────────────────────────┘
104-
▼
105-
┌─────────────────────────────────────────────────────┐
106-
│ BPE Tokenizer (from GGUF) │
107-
│ SentencePiece-compatible encoding │
108-
└─────────────────────┬───────────────────────────────┘
109-
▼
110-
┌─────────────────────────────────────────────────────┐
111-
│ Transformer Engine (Integer) │
112-
│ Q4_K/Q5_K/Q6_K/Q8_0 quantized weights │
113-
│ SIMD-accelerated matrix ops │
114-
└─────────────────────┬───────────────────────────────┘
115-
▼
116-
┌─────────────────────────────────────────────────────┐
117-
│ Hardware Abstraction │
118-
│ PCI • DMA • Memory-Mapped I/O │
119-
└─────────────────────────────────────────────────────┘
110+
| `talk` | Start interactive AI chat |
111+
| `chat <msg>` | Single message to AI |
112+
| `status` | System and AI status |
113+
| `help` | Show all commands |
114+
| `benchmark` | Run inference benchmark |
115+
| `mem` | Memory usage |
116+
| `perf` | Chat performance stats |
117+
118+
### Example Session
119+
120+
```
121+
embodios> talk
122+
You> Hello!
123+
AI> Hello! How can I help you today?
124+
You> exit
125+
126+
embodios> status
127+
AI: Ready (SmolLM-135M)
128+
Memory: 120MB / 512MB
120129
```
121130

122-
## Documentation
131+
## Supported Models
123132

124-
Full documentation available on the [EMBODIOS Wiki](https://github.com/dddimcha/embodiOS/wiki).
125-
126-
### Project Status
127-
- [Home](https://github.com/dddimcha/embodiOS/wiki) - Wiki home page
128-
- [Current State Analysis](https://github.com/dddimcha/embodiOS/wiki/Current-State-Analysis) - Project progress (75% complete)
129-
- [Three Strategic Pillars](https://github.com/dddimcha/embodiOS/wiki/Three-Strategic-Pillars) - Implementation roadmap
130-
- [Pillar 1: Ollama GGUF Integration](https://github.com/dddimcha/embodiOS/wiki/Pillar-1:-Ollama-GGUF-Integration) - AI runtime (90% complete)
131-
132-
### Quick Start Guides
133-
- [Getting Started](https://github.com/dddimcha/embodiOS/wiki/Getting-Started) - Installation and first steps
134-
- [Console Commands](https://github.com/dddimcha/embodiOS/wiki/Console-Commands) - **Complete command reference**
135-
- [Modelfile Reference](https://github.com/dddimcha/embodiOS/wiki/Modelfile-Reference) - Model configuration
136-
- [Hardware Requirements](https://github.com/dddimcha/embodiOS/wiki/Hardware-Requirements) - Supported hardware
137-
- [API Reference](https://github.com/dddimcha/embodiOS/wiki/API-Reference) - API documentation
138-
- [Contributing](https://github.com/dddimcha/embodiOS/wiki/Contributing) - How to contribute
139-
140-
### Technical Deep Dives
141-
- [Architecture Overview](https://github.com/dddimcha/embodiOS/wiki/Architecture-Overview) - System architecture
142-
- [Quantized Integer Inference](https://github.com/dddimcha/embodiOS/wiki/Quantized-Integer-Inference) - How integer-only AI works
143-
- [Performance Benchmarks](https://github.com/dddimcha/embodiOS/wiki/Performance-Benchmarks) - Benchmark results
144-
- [Bare Metal Deployment](https://github.com/dddimcha/embodiOS/wiki/Bare-Metal-Deployment) - Real hardware deployment
145-
- [Stability Testing](docs/stability_testing.md) - Long-running stability test suite
146-
147-
## Performance Targets
148-
149-
| Metric | llama.cpp | EMBODIOS v1.0 | Advantage |
150-
|--------|-----------|---------------|-----------|
151-
| **Speed** | 83-86 tok/s | 100-120 tok/s | **20-40% faster** |
152-
| **Memory** | 160 MB | 120 MB | **25% less** |
153-
| **Latency Jitter** | ±5-10ms | ±0.5ms | **10-20x better** |
154-
| **Boot Time** | N/A | <1 sec | **Instant on** |
155-
| **First Token** | ~50ms | <20ms | **2.5x faster** |
156-
| **Context Switch** | ~1-5μs | 0 | **Zero overhead** |
157-
158-
## Verified Models
159-
160-
| Model | Size | Quantization | Status |
161-
|-------|------|--------------|--------|
162-
| TinyLlama-1.1B | 638 MB | Q4_K_M | Tested |
163-
| Phi-2 | 1.7 GB | Q4_K_M | Tested |
164-
| Mistral-7B | 4.2 GB | Q4_K_M | Tested |
165-
166-
## Why Bare-Metal AI?
167-
168-
**Kernel-space AI enables:**
169-
- **Ultra-low latency:** 10x better consistency for real-time applications
170-
- **Minimal footprint:** 25% less memory for edge/embedded devices
171-
- **Direct hardware access:** No syscall overhead, zero-copy DMA
172-
- **Deterministic timing:** Critical for robotics, industrial control
133+
| Model | Size | Quantization |
134+
|-------|------|--------------|
135+
| SmolLM-135M | 469 MB | Q6_K |
136+
| TinyLlama-1.1B | 638 MB | Q4_K_M |
137+
| Phi-2-2.7B | 1.7 GB | Q4_K_M |
138+
| Mistral-7B | 4.2 GB | Q4_K_M |
173139

174-
## Contributing
140+
Any GGUF model from Ollama/HuggingFace should work.
175141

176-
```bash
177-
# Clone the repository
178-
git clone --recurse-submodules https://github.com/dddimcha/embodiOS.git
142+
## Project Structure
179143

180-
# Build and test
181-
cd kernel && make
182-
make test
144+
```
145+
embodiOS/
146+
├── embodi # CLI tool
147+
├── kernel/ # Kernel source
148+
│ ├── ai/ # AI runtime
149+
│ ├── core/ # Kernel core
150+
│ ├── drivers/ # Hardware drivers
151+
│ └── Makefile
152+
├── models/ # GGUF models
153+
├── scripts/ # Build scripts
154+
└── build/ # Output (ISO, etc.)
183155
```
184156

185-
**Choose Your Pillar:**
186-
- **Kernel hacker?** → [Pillar 2: Linux Driver Compatibility](https://github.com/dddimcha/embodiOS/wiki/Pillar-2:-Linux-Driver-Compatibility)
187-
- **AI researcher?** → [Pillar 1: Ollama GGUF Integration](https://github.com/dddimcha/embodiOS/wiki/Pillar-1:-Ollama-GGUF-Integration)
188-
- **Performance engineer?** → [Pillar 3: Performance Optimization](https://github.com/dddimcha/embodiOS/wiki/Pillar-3:-Performance-Optimization)
157+
## Performance
189158

190-
## Community
159+
| Metric | EMBODIOS | llama.cpp |
160+
|--------|----------|-----------|
161+
| Memory | 120 MB | 160 MB |
162+
| Latency jitter | ±0.5ms | ±5-10ms |
163+
| Boot time | <1 sec | N/A |
164+
| First token | <20ms | ~50ms |
191165

192-
- [Discord Server](https://discord.gg/xRsYfcdP)
193-
- [GitHub Wiki](https://github.com/dddimcha/embodiOS/wiki)
194-
- [Issues](https://github.com/dddimcha/embodiOS/issues)
166+
## Documentation
167+
168+
- [Wiki](https://github.com/dddimcha/embodiOS/wiki)
169+
- [Getting Started](https://github.com/dddimcha/embodiOS/wiki/Getting-Started)
170+
- [Console Commands](https://github.com/dddimcha/embodiOS/wiki/Console-Commands)
171+
- [Architecture](https://github.com/dddimcha/embodiOS/wiki/Architecture-Overview)
172+
173+
## Contributing
174+
175+
```bash
176+
git clone https://github.com/YOUR_USERNAME/embodiOS.git
177+
cd embodiOS
178+
git checkout -b feature/my-feature
179+
./embodi build
180+
./embodi test
181+
# Submit PR
182+
```
195183

196184
## License
197185

198-
EMBODIOS is open source software licensed under the [MIT License](LICENSE).
186+
MIT License - see [LICENSE](LICENSE)
199187

200-
---
188+
## Links
201189

202-
**EMBODIOS** - Bare-metal AI where transformers meet hardware directly.
190+
- [Discord](https://discord.gg/xRsYfcdP)
191+
- [Issues](https://github.com/dddimcha/embodiOS/issues)
192+
- [Wiki](https://github.com/dddimcha/embodiOS/wiki)

0 commit comments

Comments
 (0)