An Ubuntu-based operating system purpose-built for AI automation. Ships with OpenClaw as a first-class system service, hardened security defaults, and a setup wizard that gets you to a working AI agent in under 5 minutes.
AgentOS is a pre-configured VM image (OVA/QCOW2) that turns any virtualization platform into a dedicated AI agent appliance. Boot it up, connect your LLM provider, pair a messaging channel, and you have an always-on AI assistant running in a secure, isolated environment.
This is not "Ubuntu with OpenClaw installed." It's an opinionated, security-hardened environment where:
- The agent runs as a dedicated system user with no root access
- Every agent action is logged to an audit trail
- AppArmor profiles restrict what the agent process can touch
- Credentials are stored in a vault the agent process cannot read directly
- A setup wizard handles first-run configuration (model provider, channels, skills)
| Edition | Who it's for | What ships |
|---|---|---|
| Lite (this repo) | Anyone who wants an AI agent appliance | GNOME desktop + OpenClaw + setup wizard |
| Server (this repo) | Headless / cloud deployments | Minimal + systemd gateway + cloud-init |
| Dev (planned) | Agent developers | CLI-first + SDK + local model runtime |
# Download the latest OVA
curl -LO https://github.com/SecureAgentOS/agentos/releases/latest/download/agentos-lite.ova
# Import into VirtualBox
VBoxManage import agentos-lite.ova
VBoxManage startvm agentos-lite# Download the server QCOW2
curl -LO https://github.com/SecureAgentOS/agentos/releases/latest/download/agentos-server.qcow2
# Configure the agent before first boot
cat > /tmp/setup.conf <<'EOF'AGENTOS_PROVIDER=anthropicAGENTOS_API_KEY=sk-ant-...AGENTOS_AGENT_NAME=AtlasAGENTOS_CHANNEL=skipEOF# Boot with serial console
qemu-system-x86_64 -hda agentos-server.qcow2 -m 2048 -enable-kvm \
-nographic -serial mon:stdiogit clone https://github.com/SecureAgentOS/agentos.git
cd agentos
make validate # Check config before building
make build # Build the Lite edition (requires Ubuntu 24.04 + sudo)
make build-server # Build the Server editionThe build script requires Ubuntu 24.04 as the host (or any Debian-based system with debootstrap).
┌─────────────────────────────────────────────┐
│ Setup Wizard / Welcome App │
├─────────────────────────────────────────────┤
│ OpenClaw Gateway (systemd service) │
│ ├── Skill marketplace │
│ ├── MCP server hub │
│ └── Sandbox / permissions │
├─────────────────────────────────────────────┤
│ Security layer │
│ ├── AppArmor profiles │
│ ├── Credential vault │
│ └── Audit logging │
├─────────────────────────────────────────────┤
│ Ubuntu 24.04 LTS (Noble Numbat) │
│ Node.js 22 · Docker · GNOME (Lite only) │
└─────────────────────────────────────────────┘
- Ubuntu 24.04 host (for debootstrap compatibility)
- 20GB free disk space
sudoaccess- Internet connection (to pull packages)
agentos/
├── scripts/
│ ├── build-vm.sh # Main build orchestrator
│ ├── 01-bootstrap.sh # debootstrap base system
│ ├── 02-install-deps.sh # Node.js, Docker, OpenClaw
│ ├── 03-configure.sh # systemd units, AppArmor, users
│ ├── 04-desktop.sh # GNOME + branding (Lite only)
│ ├── 05-wizard.sh # First-run setup wizard
│ ├── 06-package.sh # Export as OVA/QCOW2
│ ├── validate.sh # Pre-build validation checks
│ └── smoke-test.sh # Post-build rootfs verification
├── config/
│ ├── apparmor/
│ │ ├── agentos-openclaw # AppArmor profile for OpenClaw agent
│ │ └── agentos-broker # AppArmor profile for credential broker
│ ├── systemd/
│ │ ├── agentos-gateway.service
│ │ └── agentos-broker.service
│ ├── audit/
│ │ └── agentos.rules # auditd rules for agent activity
│ ├── logrotate/
│ │ └── agentos # Log rotation policy
│ ├── channels/
│ │ ├── telegram.example.json # Telegram channel template
│ │ ├── discord.example.json # Discord channel template
│ │ └── slack.example.json # Slack channel template
│ └── openclaw/
│ ├── openclaw.defaults.json # Default agent config
│ └── env.template # Environment variable template
├── Makefile # Build convenience targets
├── branding/
│ ├── plymouth/ # Boot splash theme + asset generator
│ ├── grub/ # Bootloader theme + asset generator
│ ├── wallpapers/ # Desktop wallpapers (light + dark SVG)
│ ├── icons/ # App icon, favicon (SVG)
│ └── welcome/ # HTML welcome app (getting started guide)
├── docs/ # User-facing documentation
└── README.md
The Server edition is a headless, cloud-ready variant — no GNOME desktop, no Plymouth splash, no Chromium. It's designed for always-on deployments on VMs, VPS, or cloud instances.
Key differences from Lite:
| Feature | Lite | Server |
|---|---|---|
| Desktop (GNOME) | Yes | No |
| Gateway bind | 127.0.0.1 | 0.0.0.0 |
| Execution policy | ask | auto |
| Setup wizard | Interactive TUI | Config-file / cloud-init |
| Serial console | No | Yes (ttyS0,115200) |
| Cloud image | No | .raw.gz (AWS/GCP/Azure) |
| Health endpoint | No | Port 8080 |
| Chromium | Yes | No |
| cloud-init | No | Yes |
Non-interactive setup: Place /etc/agentos/setup.conf on the VM before first boot (or via cloud-init user-data):
AGENTOS_PROVIDER=anthropic
AGENTOS_API_KEY=sk-ant-...
AGENTOS_AGENT_NAME=Atlas
AGENTOS_CHANNEL=skipThe setup service runs on first boot, reads the config, and marks setup complete. On subsequent boots it is a no-op.
Health check:curl http://<vm-ip>:8080 returns 200 OK when the gateway is running, 503 DOWN otherwise. Use this for load balancer health checks.
AgentOS follows the principle of least privilege for autonomous agents:
- Dedicated user: OpenClaw runs as
agentos(uid 1100), not root - AppArmor confinement: The agent process can only access its workspace, not system files
- Credential isolation: API keys live in
/etc/agentos/vault/owned by root; the agent requests tokens through a broker service - Audit trail: Every shell command, file write, and network request is logged to
/var/log/agentos/audit.log - Docker sandboxing: Skills that need shell access run inside ephemeral containers
- Project scaffold and build scripts
- Phase 1: Bootable VM image with OpenClaw pre-configured
- Phase 2: AppArmor + credential vault + audit logging
- Phase 3: First-run setup wizard with channel pairing
- Phase 4: Branding (Plymouth, GRUB, wallpaper, welcome app)
- Phase 5: Server edition (headless, cloud-ready, non-interactive setup)
- Phase 6: Dev edition (SDK, local model support)
- Future: Bootable ISO for bare-metal installation
This project is in early development. Issues and PRs welcome.
MIT