Skip to content

Getting Started

Jump to bottom
Dmitry Dimcha edited this page Jan 29, 2026 · 3 revisions

Getting Started with EMBODIOS

Welcome to EMBODIOS - the world's first bare-metal AI operating system. This guide will help you build and run EMBODIOS with AI inference.

Prerequisites

For Building

  • Linux or macOS (with cross-compiler)
  • x86_64-elf-gcc cross-compiler
  • QEMU for testing
  • 4GB+ RAM on build machine

Install Build Tools

macOS:

brew install x86_64-elf-gcc qemu

Ubuntu/Debian:

sudo apt install build-essential qemu-system-x86 nasm
# Cross-compiler: download from https://wiki.osdev.org/GCC_Cross-Compiler

Quick Start

1. Clone the Repository

git clone https://github.com/dddimcha/embodiOS.git
cd embodiOS

2. Get a Model

Download a GGUF model (or use the included ones):

# SmolLM-135M (smallest, ~469MB) - good for testing
# TinyLlama (638MB) - better quality
# Already in models/ directory if you cloned with submodules
ls models/

3. Build the Kernel

cd kernel

# Build with embedded model
make GGUF_MODEL=../models/smollm-135m.gguf

# Or use TinyLlama for better output
make GGUF_MODEL=../models/tinyllama.gguf

4. Run in QEMU

qemu-system-x86_64 \
  -kernel embodios.elf \
  -m 1024M \
  -serial mon:stdio \
  -nographic

5. Interact with EMBODIOS

Once booted, you'll see:

EMBODIOS Ready (polling mode - no interrupts).
Type 'help' for available commands.

>

Start chatting immediately:

> talk              # Enter interactive chat mode (recommended!)

This opens a dedicated chat session:

You> Hello, how are you?
AI>  Hello! I'm doing well. How can I help you today?

You> perf           # Check performance inline
 [Session: 1 msgs, 15 tokens, 127 tok/s avg]

You> exit           # Leave chat mode

Other useful commands:

> help              # Show all commands
> help ai           # AI-specific commands
> chat Hello!       # Single message (for scripting)
> perf              # Show chat performance stats
> status            # Check AI readiness
> benchmark         # Full inference benchmark

Building a Bootable ISO

For real hardware or USB boot:

# Install ISO tools
# macOS: brew install grub xorriso
# Linux: apt install grub-pc-bin xorriso

# Build ISO with model
./scripts/create_iso.sh -m models/tinyllama.gguf

# Test ISO in QEMU
qemu-system-x86_64 -cdrom build/embodios.iso -m 1024M -serial stdio

# Write to USB (Linux)
sudo dd if=build/embodios.iso of=/dev/sdX bs=4M status=progress

Shell Commands Reference

AI Chat Commands

Command Description
talk Interactive chat mode - continuous conversation loop
chat <message> Single message chat (for scripting)
perf Show chat performance statistics
status Show AI model and system status
benchmark Run full inference benchmark

System Commands

Command Description
help Show basic commands
help ai AI-specific commands
help all All available commands
mem Show memory statistics
clear / cls Clear screen
version Show kernel version
reboot Reboot system

Hardware Commands

Command Description
lspci List PCI devices
blkdevs List block devices
netinfo Show network info
ping <ip> Ping remote host

Full command reference: Console-Commands

Example Session

> talk
 ╔════════════════════════════════════════╗
 ║         EMBODIOS Chat Mode             ║
 ╚════════════════════════════════════════╝

 Loading model (468 MB)... done.
 Initializing tokenizer... done.
 Initializing inference engine... done.

 Ready! Start chatting.

You> Once upon a time

AI>  Once upon a time, in a magical kingdom far away, there lived a young 
     princess named Aurora who loved to explore the enchanted forest...

You> perf
 [Session: 1 msgs, 28 tokens, 127 tok/s avg]

You> exit
 ────────────────────────────────────────
 Session ended.
 Messages: 1 | Tokens: 28 | Time: 220 ms
 ────────────────────────────────────────

> perf
 ╔════════════════════════════════════════╗
 ║        Chat Performance Stats          ║
 ╚════════════════════════════════════════╝

 [Last Message]
   Prompt tokens:     5
   Generated tokens:  28
   Total time:        220 ms
   Throughput:        127 tok/s

Troubleshooting

Build Fails: "x86_64-elf-gcc not found"

Install the cross-compiler:

# macOS
brew install x86_64-elf-gcc

# Linux - build from source or use package manager

QEMU: "could not connect serial device"

Use -serial mon:stdio instead of -serial stdio

Model Too Large

Use a smaller model:

  • SmolLM-135M (469MB) - fastest
  • TinyLlama (638MB) - good balance
  • Don't embed Phi-2 (1.7GB) unless you have lots of RAM

Inference Very Slow in QEMU

This is normal - QEMU is emulating x86_64 (especially slow on ARM Macs). Real performance comes from native hardware. Expect:

  • QEMU: ~1-5 tok/s
  • Native x86_64: ~85-120 tok/s

Hardware Requirements

Minimum

  • x86_64 CPU with SSE2
  • 512 MB RAM
  • USB boot support

Recommended

  • x86_64 CPU with AVX2
  • 2+ GB RAM
  • NVMe SSD for model storage

Tested Hardware

  • Intel NUC (various generations)
  • QEMU x86_64 emulation
  • VirtualBox (limited)

Next Steps

Getting Help

Welcome to bare-metal AI! 🚀

Clone this wiki locally