Claw OS

The world’s first agent-native operating system from the future.

Claw OS is under active development; its architecture, APIs, and behavior may change significantly.

Why Claw OS is agent-native

Agent-native is the whole bet: the next operating system is one where the assistant is not a tab you open but the layer the system runs through. Here that means:

• The AI is part of the system, not an app on top of it. It runs as a privileged system service, not in a sandbox, so you can just ask the things an app could never reach — "why is my network so slow?", "why did that app just crash?", "why can't I get online?", "what's eating my disk?" — and it actually looks at your processes, logs, network, and resources to answer.
• It understands every app. The agent can inspect which apps are installed and used, what permissions they have, what resources they can access, their activity and history, their logs, and the evidence behind a crash. It can connect that app context with the rest of the system instead of diagnosing each app in isolation.
• One agent across every app. Instead of a separate, siloed assistant inside each app, a single agent spans the whole machine — it can drive several apps in one request (read a document, draft an email, post a notification) and reasons from real system state, not just one app's view.
• It remembers. The agent has persistent memory across conversations: what you did in your apps, what changed on the system, your preferences, and context that carries from one app to the next — so you never re-explain yourself. It's your memory; you can review it and forget any of it, down to a single app.
• Every app can use the system's models. Apps call the built-in model layer through the Claw OS SDK, whether the model runs locally or through a configured cloud provider. Developers can build AI-powered apps without embedding a model or rebuilding provider integration, credentials, consent, budgets, safety, and logging.
• Local-first. The system's intelligence belongs on your own machine, not someone else's servers. As edge hardware (CPU / GPU / NPU) matures, fully on-device "edge AI" becomes the default; today it runs local models where your hardware can handle it and falls back to cloud AI APIs where it can't — without changing how you use it.
• Apps open up to the agent. Every app publishes what it can do and the permissions it needs through the claw-os-sdk (Rust, Python, Node, Go). The agent can discover and call those APIs, then combine operations from multiple apps into complex workflows.
• Safe by construction. Every privileged action goes through a capability check and your approval, so "system-level" never means "unrestricted" — looking, changing, and touching the kernel are each gated separately. Primitives return structured, machine-readable data instead of scraped UI, and setting up, asking, chatting, and diagnosing are first-class parts of the OS. Agent consent is bound to the exact validated capability rather than a coarse tool name; see Capability-aware Agent consent.

Together, the system-level agent, persistent memory, local-first model runtime, scoped permission model, cross-app session store, audit trail, and app SDK form one integrated agent-native OS layer.

Application products are developed in clawos-app and composed into signed OS packages from an immutable source pin. Native Notifications now lives there with its complete UI/MCP/config/util source; Claw OS retains notification authority, durable state and delivery. The migration plan distinguishes source ownership from pending legacy data and visual cutovers.

Quick Start

Ubuntu — install the Agent layer without replacing Ubuntu

Install the signed claw-os-agent package on an existing Ubuntu system:

sudo install -d -m 0755 /usr/share/keyrings

curl -fsSL https://xiaoyu-work.github.io/claw-os/claw-os-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/claw-os-archive-keyring.gpg >/dev/null

ARCH="$(dpkg --print-architecture)"
echo "deb [arch=$ARCH signed-by=/usr/share/keyrings/claw-os-archive-keyring.gpg] https://xiaoyu-work.github.io/claw-os trixie main" \
  | sudo tee /etc/apt/sources.list.d/claw-os.list >/dev/null

sudo apt update
sudo apt install claw-os-agent

Verify the daemon:

systemctl is-enabled clawd.service
systemctl is-active clawd.service
sudo systemctl status clawd.service --no-pager

WSL — recommended

Install the latest successfully published main WSL distribution (wsl-latest, rolling pre-release):

$arch = if ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") { "arm64" } else { "amd64" }
$package = "claw-os-wsl-$arch.wsl"
$url = "https://github.com/xiaoyu-work/claw-os/releases/download/wsl-latest/$package"
$installPath = "C:\WSL\claw-os"

curl.exe -L --fail --retry 5 --retry-delay 3 -C - --output $package $url
wsl --install --from-file ".\$package" --name claw-os --location $installPath --version 2

Docker / OrbStack — recommended

Run the container:

docker pull ghcr.io/xiaoyu-work/claw-os:latest
mkdir -p ./workspace
docker run -d --name claw --privileged \
  -e CLAW_USER=yourname \
  -v ./workspace:/workspace \
  ghcr.io/xiaoyu-work/claw-os:latest
docker exec -it claw /usr/local/sbin/claw-container-entrypoint shell

Replace yourname with the UNIX username to create. The default UID/GID is 1000; set CLAW_UID and CLAW_GID when a Linux host needs numeric ownership to match a bind mount.

Headless VM — experimental

Build and boot the default headless QEMU image:

sudo ./build.sh vm
qemu-system-x86_64 -m 2G -nographic \
  -drive file=build/claw-os-vm-amd64.qcow2,format=qcow2,if=virtio

On first boot, the serial console requires you to set a password for the locked cos account before it starts the normal login prompt. The image ships with no default password. Then log in as cos with the password you just set; sudo uses the same password.

Desktop / ISO / VM — experimental

Build a bootable desktop VM disk image and load it in VMware — see Building the Claw OS Desktop Image for the steps on Windows (WSL2), macOS, and Linux.

Azure Compute Gallery — generalized fixed VHD

Build a generalized Hyper-V Generation 2 fixed VHD:

sudo ./build.sh azure

Azure supplies the administrator and SSH key for each VM through cloud-init. See Building an Azure Compute Gallery image for desktop builds and publishing commands.

Updating an existing installation

Package-level fixes to cos, clawd, bundled apps, browser automation, and systemd units do not require reinstalling the operating system or replacing its image. Claw OS uses the same signed APT update path across WSL, installed desktop/VM systems, Azure instances, and long-running containers:

sudo apt update
sudo apt full-upgrade

See Updating Claw OS for repository checks, setup for older images, service restart behavior, container guidance, and the exceptional cases that require a new image.

Drive the OS with the agent

Call structured system primitives directly, or ask the built-in agent to choose and combine them:

cos  # list primitives
cos app web read https://example.com  # fetch URL → {url, title, text, links}
cos agent setup text  # configure the conversational text model
cos agent ask "why is my network so slow right now?"
cos agent ask "why did my last app crash?"
cos agent chat  # interactive REPL with cross-app memory

License

Apache-2.0 for original Claw OS components. See the NOTICE for vendored sources and their upstream licenses.