Why an AI-Native Operating System?​

Current AI agent frameworks typically operate as Python CLI wrappers or desktop applications that execute untrusted scripts directly in user environments. While convenient for quick experimentation, this paradigm suffers from critical limitations when running autonomous systems long-term:

1. Lack of Isolation: Scripts running directly on host machines can accidentally delete files or exhaust CPU/RAM resources.
2. Plaintext Secrets: API keys and OAuth tokens are frequently stored unencrypted in .env files or JSON configs.
3. Fragile State & Restarts: Crashes or power cuts erase running tasks without durable checkpoint recovery.
4. Complex Network Setup: Exposing agents across private home networks often requires insecure port forwarding.

ActonOS rethinks this from the ground up by placing agents, sandboxed tooling runtimes, hybrid semantic memory, and hardware-bound encryption directly into the core operating system layer.

Key Highlights of ActonOS v0.1​

1. Dual-Runtime Hardware Abstraction Layer (HAL)​

ActonOS compiles into a single static Go daemon (actond, CGO_ENABLED=0) that automatically detects whether it is running on Bare-Metal MiniPC hardware or inside a Docker Container:

• On Bare-Metal MiniPCs, it interfaces with Linux D-Bus, manages Wi-Fi Captive Portal hotspots (ActonOS-XXXX), enforces Bubblewrap namespaces, and governs CPU/RAM limits via Cgroups v2.
• In Docker, it provides a pre-configured, batteries-included agent runtime with Python, Node.js, Chromium, and Ripgrep.

2. Multi-Agent Swarm & Delegation​

Create unlimited AI agents with custom personas, LLM cascade routers (OpenAI, Claude, Gemini, DeepSeek, Ollama), and tool scopes. Agents can delegate tasks to specialized child agents concurrently via Go Goroutines, with structured approval ledgers for high-risk mutations.

3. Dynamic Tooling Hub (MCP, WASM & Skills)​

Hot-load external capabilities at runtime without restarting the daemon:

• Model Context Protocol (MCP): Native stdio and HTTP/SSE JSON-RPC client.
• WebAssembly Plugins: Pure-Go WASI runtime powered by wazero.
• Skill-as-a-Folder: Auto-reloading directory scripts (skill.json + run.sh/run.py) with fsnotify.

4. Hybrid Semantic Memory (RAG)​

Combines SQLite FTS5 lexical keyword matching with Chromem-go local vector embeddings generated by the pinned multilingual-e5-small ONNX model. Incorporates a 1-minute durable debounce queue and Ebbinghaus forgetting curve decay.

5. Hardware-Bound Vault & Cryptographic Audit Trail​

API keys and OAuth 2.1 PKCE tokens are encrypted with AES-256-GCM keys derived from physical system hardware identifiers (DMI UUID + CPU serial) via Argon2id. Every security event is chained in an immutable SHA-256 ledger (audit.jsonl).

6. Zero-Config Remote Access via Tailscale tsnet​

The core daemon embeds Tailscale's pure-Go tsnet client directly, providing an encrypted WireGuard mesh connection and automatic HTTPS domain (https://acton.<tailnet>.ts.net) without opening inbound router firewall ports.

Getting Started​

You can deploy ActonOS in under a minute with Docker:

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

Or flash the bootable ActonOS-v0.1.iso onto a USB drive to turn any Intel N100 or AMD Ryzen MiniPC into a dedicated AI appliance.

• 📖 Read the Documentation: Getting Started Guide
• 🐙 Explore the Codebase: GitHub Repository
• 💬 Join the Community: Discord Server

The Challenge of Dual Deployments​

When designing an autonomous AI operating system, two competing developer requirements emerge:

1. Appliance Experience: Users want to buy a $150 Intel N100 MiniPC, flash an ISO, and have a turnkey, dedicated server that self-heals over OTA and configures via Wi-Fi captive portal.
2. Infrastructure Flexibility: Cloud operators, NAS users, and home-lab tinkerers want to run ActonOS inside existing Docker Compose or Kubernetes stacks without privileged root access.

Attempting to force container mechanics onto bare metal (or vice versa) results in brittle scripts. Instead, ActonOS implements a clean Dual-Runtime HAL interface in Go:

type HardwareAbstractionLayer interface {
    GetRuntimeMode() RuntimeMode
    GetSystemTelemetry() (TelemetrySnapshot, error)
    SpawnSandbox(ctx context.Context, cmd Spec) (ProcessHandle, error)
    ConfigureNetwork(cfg NetworkConfig) error
    ApplyOTAUpdate(releaseVersion string) error
}

Bare-Metal Mode: Kernel Namespaces & Cgroups v2​

On physical hardware, the HAL activates the Bare-Metal Driver:

• Bubblewrap (bwrap) Sandboxing: Rather than running scripts as root or a generic user, tool calls spawn an unprivileged Bubblewrap namespace. The root filesystem is mounted strictly read-only, /etc and /data/config are unmounted, and only /data/workspace is writable.
• Cgroups v2 Resource Governance: Each sandboxed execution is assigned to a dynamic Cgroups v2 slice with hard caps:
  • memory.max: 512 MB (Kernel OOM terminates only the rogue process).
  • cpu.max: 50000 100000 (Max 50% single-core quota).
  • pids.max: 30 (Guarantees protection against fork-bombs).
• D-Bus Integration: Direct communication with Linux NetworkManager for captive portal hotspot creation (192.168.4.1) and thermal sensors.

Docker Mode: Jailed Subshell & Container Telemetry​

When running inside a container (detected via /.dockerenv or RUNTIME_MODE=docker):

• Non-Root Execution: The daemon runs under the unprivileged acton user (UID 1000).
• Subshell Jailing: Commands are executed within a constrained subshell environment with strict path scoping and environment sanitization.
• Container Telemetry: Real-time CPU and memory metrics are read dynamically from /sys/fs/cgroup/ to reflect accurate container resource utilization rather than misleading host totals.

Summary​

By decoupling hardware management from higher-level agent reasoning, ActonOS delivers identical tool and multi-agent capabilities across both home MiniPCs and enterprise cloud servers.

Read more in our Advanced Architecture Guide.

The Problem: Token Bleed During Idle Pulses​

In traditional AI automation systems, background polling jobs repeatedly invoke LLMs on a timer to ask: "Is there any work to do?".

When no tasks are pending, weaker or faster models frequently respond with generic conversational chatter (e.g., "Hello! I am ready to help you today"), burning API tokens 24 hours a day and generating unwanted notification spam.

The Solution: The OpenClaw Zero-Waste Contract​

ActonOS v0.1 implements three key safeguards:

1. Zero-Model Idle Pulse​

If the task backlog is empty and there is no actionable directive in HEARTBEAT.md, the Heartbeat engine does not invoke the LLM at all. It returns an instantaneous, cost-free internal HEARTBEAT_OK acknowledgement.

2. Autonomous Headless System Prompt Rules​

When an actionable task is present, the routine cycle injects an explicit rule block into the model's system prompt:

[AUTONOMOUS HEADLESS EXECUTION MODE]
There is no human in the loop for this turn. Do not greet or ask how you can help.
If the directive is satisfied or no action is required, output ONLY: HEARTBEAT_OK

3. Idle Chatter Safety Filter (looksLikeIdleChatter)​

If a model disregards the directive and outputs conversational small talk without calling any tools, ActonOS intercepts the response, classifies it as nominal, and suppresses the notification.

4. Active Hours & Trigger Cooldown​

Operators can define active operating windows (e.g., 08:00 to 22:00), ensuring background agents do not trigger pulses during sleeping hours. A 15-second trigger cooldown prevents trigger storms from generating duplicate notification bursts.

Conclusion​

By adopting the OpenClaw Heartbeat contract, ActonOS allows agents to remain vigilant 24/7 with zero idle token consumption.

Explore the Automations & Heartbeat Guide for complete configuration instructions.