Skip to content

viralcode/tensoragentos

BranchesTags

Repository files navigation

TensorAgent OS

TensorAgent OS

An AI-native operating system.

TensorAgent OS screenshot

⬇️ 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:

  1. debootstrap an Ubuntu 24.04 Noble rootfs.
  2. Install Qt6, Node.js, PAM, Wayland, and other system packages.
  3. Drop in rootfs-overlay/ (systemd units, configs).
  4. Build & install OpenWhale + WhaleOS into /opt/ainux/.
  5. 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

About

Worlds first AI native agentic Operating System

tensoragentos.org/

Resources

Readme

License

View license
Activity

Stars

21 stars

Watchers

0 watching

Forks

8 forks
Report repository

Releases 4

v0.1.2 Latest
Mar 9, 2026
+ 3 releases

Packages

 
 
 

Contributors

Languages