TensorAgent OS

An AI-native operating system.

⬇️ Downloads

Architecture	ISO	VM Image
x86_64 (Intel/AMD PCs)	tensoragent-os-x86_64.iso.xz	—
ARM64 (Apple Silicon, RPi)	tensoragent-os-aarch64.iso.xz	Pre-built VM

Flash to USB:sudo dd if=tensoragent-os-x86_64.iso of=/dev/sdX bs=4M status=progress
Boot in VM: Use VirtualBox, VMware, UTM, or QEMU.
Default login:ainux / ainux

What is TensorAgent OS?

TensorAgent OS is a bootable Linux-based OS where an AI agent is the primary user interface. Instead of clicking through menus, you talk to the system. The agent has native access to:

The kernel (system calls, processes, namespaces)
Hardware (battery, sensors, audio, displays via systeminformation)
The filesystem and network stack
systemd services and package management
A WebMCP-enabled Chromium for tool use inside web pages
A pluggable skills + tools layer through OpenWhale

It ships as either a full bootable ISO (via debootstrap + Ubuntu 24.04 LTS) or as a pre-built UTM/QEMU image you can boot in seconds on macOS.

Architecture at a glance

Layer	Component	Tech
AI engine	OpenWhale	TypeScript, multi-agent, MCP, tools, skills
Desktop shell	WhaleOS	Qt6 / QML, native C++ helpers
Core orchestrator	@ainux/core	Node.js — IPC, process mgmt, hardware bridge
Browser	ainux-chromium	Chromium + WebMCP patches, kiosk/agentic mode
Optional GUI	packages/gui	React + Vite (alternative to QML shell)
Build system	scripts/build-iso.sh	debootstrap + xorriso + (optional) Buildroot

Quick Start — UTM on macOS (recommended, easiest)

The fastest path. Double-click and boot.

brew install --cask utm
open utm_build/TensorAgentOS.utm

Login:ainux / ainux

Pre-configured with 6 GB RAM, 6 cores, ARM64 virtualisation, and host port forwarding:

Host port	Guest service
`7777`	OpenWhale API / dashboard
`2222`	SSH

⚠️ If the VM hangs at the EFI shell or the desktop never appears, that's a known issue — try a cold restart from UTM and give it 2–3 more minutes. First boot runs cloud-init and can take a while.

Quick Start — QEMU on macOS (ARM64, HVF accelerated)

brew install qemu
# 1. Download an Ubuntu Server 24.04 ARM64 cloud image (~580 MB)
curl -L -o vm/ubuntu-server.qcow2 \
"https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-arm64.img"# 2. Launch (first boot ≈ 5 minutes — cloud-init installs everything)
python3 vm/launch-ainux.py

After it finishes provisioning:

Service	Where
Desktop	The QEMU window
API / Dashboard	http://localhost:7777
SSH	`ssh ainux@localhost -p 2222`

The launcher script (vm/launch-ainux.py) injects all of packages/whaleos/, the OpenWhale patch script, and the login HTML into the guest via cloud-init, so any local changes are picked up on the next boot.

Build a Bootable ISO from Source (Linux x86_64 host)

ISOs are built automatically by GitHub Actions for both x86_64 and ARM64. Download the latest from the Releases page, or build from source using the instructions below.

Reproducible from-scratch ISO build. Linux x86_64 host required, ~16 GB RAM and ~150 GB free disk recommended (less if you skip Chromium).

# 1. Install host build dependencies
sudo apt install -y \
build-essential git python3 wget curl xz-utils \
gcc g++ make tar patch pkg-config \
debootstrap xorriso grub-pc-bin grub-efi-amd64-bin \
mtools squashfs-tools qemu-user-static binfmt-support
# 2. Build the ISO
./scripts/build-iso.sh # x86_64, full build (slow)
./scripts/build-iso.sh --skip-chromium # use Ubuntu's chromium, much faster
./scripts/build-iso.sh --arch=aarch64 # cross-build ARM64 ISO
./scripts/build-iso.sh --clean # nuke ./build and start over# 3. Smoke-test in QEMU
./scripts/run-qemu.sh

The build pipeline (see scripts/build-iso.sh) does:

debootstrap an Ubuntu 24.04 Noble rootfs.
Install Qt6, Node.js, PAM, Wayland, and other system packages.
Drop in rootfs-overlay/ (systemd units, configs).
Build & install OpenWhale + WhaleOS into /opt/ainux/.
Install the GRUB bootloader and generate the ISO with xorriso.

Flash to USB

# Replace /dev/sdX with the right device — this WILL erase it.
sudo dd if=ainux.iso of=/dev/sdX bs=4M status=progress conv=fsync
sync

Build a UTM Bundle (macOS)

Wrap a generated qcow2 disk into a ready-to-double-click UTM VM:

# 1. Produce vm/ainux.qcow2 first
python3 vm/launch-ainux.py
# 2. Stage the bundle
mkdir -p utm_build/TensorAgentOS.utm/Data
cp vm/ainux.qcow2 utm_build/TensorAgentOS.utm/Data/ainux.qcow2
# 3. Drop in the config.plist (template lives in utm_build/)# 4. Open
open utm_build/TensorAgentOS.utm

Note: UTM does not run cloud-init on its own. Make sure the disk image already has systemd-networkd DHCP configured, otherwise the VM will boot with no network and the agent will look broken.

Project Layout

ainux/
├── packages/
│ ├── openwhale/ # OpenWhale AI engine (TS) — agents, MCP, skills, tools
│ ├── whaleos/ # Qt6 / QML desktop shell — main.qml, ChatBar, Desktop, …
│ ├── core/ # Node.js core orchestrator — IPC, hardware, process mgmt
│ ├── chromium/ # Chromium patches: WebMCP-on, AInux hooks, kiosk mode
│ └── gui/ # Optional React/Vite shell (alternative front-end)
├── buildroot-external/ # Custom Buildroot packages (ainux-shell, ainux-gui, …)
├── board/ainux/ # Bootloader configuration (GRUB)
├── configs/ # Buildroot defconfig + kernel .config
├── rootfs-overlay/ # Files copied into the rootfs (systemd units, /etc, /opt)
├── scripts/
│ ├── build-iso.sh # Master build script (Ubuntu-based)
│ ├── run-qemu.sh # Launch the built ISO in QEMU
│ ├── integrate-openwhale.sh
│ ├── configure-rendering.sh
│ ├── post-build.sh / post-image.sh
│ └── ainux-update.sh # In-guest updater
├── vm/
│ ├── launch-ainux.py # One-command QEMU launcher (ARM64 + HVF on macOS)
│ ├── boot-ainux.sh # Plain boot script
│ ├── auto-setup.sh # In-guest first-boot setup
│ └── cidata/ # cloud-init seed (meta-data / user-data)
├── utm_build/ # Pre-built UTM virtual machine bundle
├── docs/ # Project docs (HTML)
└── package.json # npm workspace root

Development Workflow

Hot-reload changes into a running VM over SSH:

# WhaleOS (QML) — restart shell after copying
scp -P 2222 packages/whaleos/*.qml ainux@localhost:/opt/ainux/whaleos/
ssh -p 2222 ainux@localhost "sudo systemctl restart ainux-gui"# OpenWhale (TypeScript) — rebuild + restart in-guest
scp -P 2222 packages/openwhale/src/**/*.ts ainux@localhost:/tmp/
ssh -p 2222 ainux@localhost " sudo cp /tmp/*.ts /opt/ainux/openwhale/src/ && cd /opt/ainux/openwhale && sudo npm run build && sudo systemctl restart openwhale"# Tail logs
ssh -p 2222 ainux@localhost "journalctl -u openwhale -u ainux-gui -f"

There's also a convenience script: scripts/dev-push.sh.

NPM scripts (host side)

npm run dev # Run OpenWhale directly on the host (no VM)
npm run build:shell # Build the WhaleOS QML shell locally
npm run build:iso # Build the x86_64 ISO
npm run build:iso:arm64
npm run setup:vm # Provision vm/ contents
npm run test:qemu # Boot the latest ISO in QEMU
npm run lint

Default credentials everywhere:ainux / ainux (login, sudo, SSH). Change them before exposing the VM to anything other than localhost.

Known Issues / Rough Edges

A non-exhaustive list — please add to it via GitHub issues:

Live ISO only. The ISO currently boots live; persistence is whatever the underlying VM disk gives you. No installer yet.
First-boot cloud-init can hang. If you don't see the desktop after ~10 minutes, SSH in on 2222 and run cloud-init status --long.
WhaleOS shell crash on resize. Resizing the QEMU/UTM window can take the QML shell down. Restart with sudo systemctl restart ainux-gui.
OpenWhale agents may stall waiting on a tool call that never returns. Restart with sudo systemctl restart openwhale.
Chromium kiosk patches are out of date for some upstream versions; use --skip-chromium if the build fails.
ARM64 cross-build of Chromium is essentially untested.
No installer. The ISO currently boots live; persistence is whatever the underlying VM disk gives you.
Networking in UTM can come up without a route on some macOS versions. sudo dhclient enp0s1 (or similar) usually fixes it.

Contributing

Issues and PRs welcome — especially:

Reproducible bug reports (host OS, arch, exact command, full log).
Cleanups in scripts/build-iso.sh (it's grown organically).
Additional OpenWhale skills under packages/openwhale/skills/.
New QML apps under packages/whaleos/.

Please keep changes focused and avoid bundling unrelated refactors.

License

Business Source License 1.1 (BUSL-1.1) — see LICENSE. Production use requires a commercial license before 2050-04-22.

Author: JIJO JOHN — https://jijojohn.me

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
ansible		ansible
board/ainux		board/ainux
buildroot-external		buildroot-external
configs		configs
docs		docs
k8s		k8s
packages		packages
rootfs-overlay		rootfs-overlay
screenshot		screenshot
scripts		scripts
vm		vm
vmware_build		vmware_build
.dockerignore		.dockerignore
.gitignore		.gitignore
.nojekyll		.nojekyll
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
package.json		package.json
start-gui.sh		start-gui.sh

Navigation Menu

Repository files navigation

TensorAgent OS

⬇️ Downloads

What is TensorAgent OS?

Architecture at a glance

Quick Start — UTM on macOS (recommended, easiest)

Quick Start — QEMU on macOS (ARM64, HVF accelerated)

Build a Bootable ISO from Source (Linux x86_64 host)

Flash to USB

Build a UTM Bundle (macOS)

Project Layout

Development Workflow

NPM scripts (host side)

Known Issues / Rough Edges

Contributing

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

TensorAgent OS

⬇️ Downloads

What is TensorAgent OS?

Architecture at a glance

Quick Start — UTM on macOS (recommended, easiest)

Quick Start — QEMU on macOS (ARM64, HVF accelerated)

Build a Bootable ISO from Source (Linux x86_64 host)

Flash to USB

Build a UTM Bundle (macOS)

Project Layout

Development Workflow

NPM scripts (host side)

Known Issues / Rough Edges

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages