actonos

ActonOS

Extensible AI Agent Operating System Kernel

A single-purpose appliance OS designed as a customizable, self-governing agent kernel that runs 24/7. ActonOS keeps its core daemon (actond) statically linked and packages local ONNX inference as a loopback-only helper for bare-metal MiniPCs and Docker containers.

Architecture · Development · Deployment · API Reference · Contributing

Key Features

Architecture Overview

graph TB
    subgraph "Layer 1 — Connectivity & Ingress"
        TSNET["Tailscale tsnet<br/>E2E Mesh VPN"]
        WEBUI["Web UI SPA<br/>React 19 + Tailwind v4"]
        CHANNELS["WASM Channel Adapters<br/>Discord · Zalo · plugin SDK"]
        PORTAL["Zero-Config Portal<br/>Captive DNS @ 192.168.4.1"]
    end

    subgraph "Layer 2 — Agent Framework"
        CONFIGURATOR["Universal Agent<br/>Configurator"]
        SWARM["Swarm Orchestrator<br/>Goroutine Delegation"]
        DELEGATION["Zero-Trust<br/>Scope Delegation"]
    end

    subgraph "Layer 3 — Auth & Integrations"
        OAUTH["OAuth 2.1 Engine<br/>PKCE S256 + DCR"]
        REFRESH["Token Refresh<br/>Daemon"]
        CONNECTORS["WASM SaaS Connectors<br/>GitHub · Notion · Linear · Custom"]
    end

    subgraph "Layer 4 — Dynamic Tooling & Extensions"
        MCP["MCP Host Engine<br/>stdio / SSE"]
        WASM["WasmLoader (Wazero JIT)<br/>Tools · Channels · Connectors"]
        SKILLS["Skill-as-a-Folder<br/>fsnotify hot-reload"]
    end

    subgraph "Layer 5 — Acton Daemon Core"
        BUS["Unified Event Bus"]
        REACT_LOOP["ReAct Orchestrator"]
        CASCADE["Model Cascade Router"]
        MEMORY["Hybrid Memory Engine<br/>FTS5 + Vector + Ebbinghaus"]
        VAULT["Encrypted Vault<br/>AES-256-GCM"]
    end

    subgraph "Layer 6 — HAL"
        BARE["Bare-metal Mode<br/>NetworkManager · bwrap · Cgroups v2"]
        DOCKER["Docker Mode<br/>Container Metrics · Jailed Exec"]
    end

    subgraph "Layer 7 — Base OS"
        DEBIAN["Debian 12 Minimal"]
        ALPINE["Alpine Linux"]
    end

    WEBUI --> CONFIGURATOR
    CHANNELS --> BUS
    TSNET --> WEBUI
    PORTAL --> WEBUI
    CONFIGURATOR --> SWARM
    SWARM --> DELEGATION
    DELEGATION --> OAUTH
    OAUTH --> REFRESH
    REFRESH --> CONNECTORS
    CONFIGURATOR --> MCP
    CONFIGURATOR --> WASM
    CONFIGURATOR --> SKILLS
    MCP --> BUS
    WASM --> BUS
    SKILLS --> BUS
    BUS --> REACT_LOOP
    REACT_LOOP --> CASCADE
    REACT_LOOP --> MEMORY
    CASCADE --> VAULT
    MEMORY --> VAULT
    BARE --> DEBIAN
    DOCKER --> ALPINE
    BUS --> BARE
    BUS --> DOCKER

Quick Start

Docker (Recommended)

docker run -d \
  --name actonos \
  -p 8080:8080 \
  -v ./acton-data:/data \
  -e RUNTIME_MODE=docker \
  --restart unless-stopped \
  actonos/actonos:latest

Open http://localhost:8080 to access the dashboard.

Bare-metal MiniPC

1. Download the latest ActonOS-vX.Y.Z.iso from Releases
2. Flash to USB: dd if=ActonOS-v1.0.0.iso of=/dev/sdX bs=4M status=progress
3. Boot the MiniPC from USB — installation is fully automated
4. Open the Web UI on the LAN (or Tailscale) and complete the setup wizard

Development

Prerequisites

Getting Started

# Clone the repository
git clone https://github.com/actonos/actonos.git
cd actonos

# Install dependencies
make deps

# Run in development mode (backend + frontend hot-reload)
make dev

# Run tests
make test

# Build production binary
make build

See docs/DEVELOPMENT.md for the full A-Z development guide.

Project Structure

actonos/
├── cmd/actond/              # Binary entrypoint (auto-detects bare-metal vs Docker)
├── cmd/embeddingd/          # Loopback multilingual-e5-small ONNX helper
├── internal/
│   ├── agent/               # AI Agent Engine, Swarm, Planner, Verifier, Memory Reflection
│   ├── auth/                # OAuth 2.1 PKCE, Token Refresh, Delegation Manager
│   ├── bus/                 # Event-Driven Pub/Sub Channel Router
│   ├── channels/            # Message routing, session state, pairing manager, account sync
│   ├── plugin/              # WasmLoader runtime (Wazero), host syscalls, tool/channel/connector bridges
│   ├── llm/                 # LLM Provider Interface & Cascade Router
│   ├── tools/               # MCP Host, WASM Runner, Skill Watcher, Native Tools
│   ├── sandbox/             # Bubblewrap (bare-metal) & Subshell (Docker) executors
│   ├── memory/              # Durable embedding queue, SQLite FTS5, Chromem, decay, Vault
│   ├── system/              # HAL, Tailscale tsnet, OTA, Hardware Metrics
│   └── server/              # HTTP Router, WebSocket, REST APIs, Static Asset Server
├── web/                     # React 19 + Tailwind v4 + Vite frontend
├── deploy/
│   ├── docker/              # Dockerfile & docker-compose.yml
│   └── live-build/          # Debian live-build ISO generation
├── scripts/                 # Dev tools, version bump, changelog, build scripts
├── docs/                    # Architecture, Development, Deployment, API, Security
├── Makefile                 # Unified build pipeline
├── VERSION                  # Source-of-truth version (SemVer)
└── CHANGELOG.md             # Keep a Changelog format

Tech Stack

Contributing

We welcome contributions! Please read our Contributing Guide for details on:

• Code style and conventions
• Branch naming and commit message format (Conventional Commits)
• Pull request process
• Release workflow

Security

For security vulnerabilities, please see our Security Policy. Do not file public issues for security bugs.

License

ActonOS is licensed under the Apache License 2.0.

Copyright 2026 ActonOS Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0