A visible local-first execution environment for AI agents.
Archeum Agent OS runs an AI agent inside a real Ubuntu VM with a branded desktop shell, live task log, desktop vision, and host-controlled permissions.
On This Page
01 — What Agent OS is
What Agent OS is
Archeum Agent OS is built for the moment where running an agent stops being abstract and starts feeling like an operating system.
You can boot the guest, watch it work, open real apps, inspect task history, save clean snapshots, and keep risky capabilities behind explicit switches.
The project combines a host controller, a real Ubuntu guest, a guest agent service, and a visible browser UI for running and inspecting agent work.
02 — System architecture
System architecture
The browser UI talks to a Node.js host controller. The host controller boots and manages a QEMU Ubuntu guest. Inside the guest, the Archeum agent service and desktop shell execute tasks and report structured events back to the host.
The result is a local execution surface where users can see the desktop, read logs, trigger actions, and keep control over what the agent is allowed to do.
- Browser UI
- Node host controller
- QEMU Ubuntu guest
- Archeum guest agent service
- Archeum desktop shell
- task events, screenshots, and logs
03 — What works today
What works today
The current repository already covers the core local loop: booting the VM, connecting to a visible desktop, running actions, logging events, and preserving host-side state.
- boot, stop, snapshot, and reset the VM
- connect to a real Ubuntu desktop through noVNC
- open Firefox, Terminal, Files, Settings, Mousepad, and utility apps
- run shell commands through the guest agent with live logs
- test Gemini provider connectivity from the UI
- use desktop actions such as screenshot, click, type, wait, browser open, and keypress
- analyze the live desktop with the Vision action
- persist history, notifications, permissions, project folder state, and snapshot metadata
04 — Quick start
Quick start
The repo currently targets a local ARM64 Ubuntu guest flow on macOS. It is not yet packaged as a cross-platform installer.
Install dependencies, make sure QEMU is available, create the VM disk and cloud-init seed, then start the host app and open the local UI.
- npm run vm:create
- npm start
- open http://localhost:8787
- npm run vm:install-agent
- npm run vm:customize
- npm run vm:install-desktop
05 — Permission model
Permission model
Agent OS is designed around host-side permission enforcement so demos and experiments do not require handing the agent unrestricted access.
Current capability switches include network access, desktop control, software install or remove, and privileged commands.
- network access
- desktop control
- software install/remove
- privileged commands
06 — Desktop surfaces
Desktop surfaces
The guest includes real applications as well as Archeum-native surfaces for working with agent tasks and system state.
- Command Palette
- Control Center
- Permissions
- Projects
- Snapshot Timeline
- Task Replay
- Tool Library
- Widgets
- Welcome