v0.1 · agent native linux

The first agent native operating system.

Claw OS is a complete Linux distribution rebuilt around the agent. Structured cos primitives, scoped approvals, a system-level broker, and a local model runtime — so an agent can drive your machine without guessing at the shell.

Install Claw OS View on GitHub
wsl wsl --import claw-os C:\WSL\claw-os claw-os-wsl-amd64.tar.gz --version 2 && wsl -d claw-os
cos · agent ask
live
cos agent ask "draft a reply to mom's latest email"
approval 2 capabilities requested scoped · one-time
  • secret.read gmail-oauth allow once
  • ai.chat claude-sonnet · draft only allow once
drafted 1 reply · saved to inbox/drafts
audit cos agent show $task — every call is in the journal
runs on WSL Docker OrbStack · amd64 arm64 · desktop & ISO · experimental
the big idea

A shell wrapper can guess. An OS can guarantee.

Most "AI for Linux" projects bolt an LLM onto bash. Claw OS instead gives the agent typed operating-system surfaces, so every action is named, gated, audited, and undoable.

Bare Linux + a shell-wrapped LLM
  • Holds a wide sudo token; risky ops blend in with safe ones.
  • Every call is unaudited — no journal, no redaction, no replay.
  • Local model lifecycle, secrets, jobs each have ad-hoc tooling.
  • Agent-vs-user boundary is invisible to the OS.
Claw OS
  • Every risky op is a typed capability and waits at an approval gate.
  • Every call lands in an append-only journal — replayable, redacted.
  • Models, engines, credentials, jobs are first-class kernel surfaces.
  • A boot-time clawd service owns the agent / user boundary.
primitives

Eight kernel surfaces. All speak JSON.

Every cos <primitive> <command> returns structured output. Agents reason about state instead of guessing it.

agent

OS-native agent runtime — sessions, tools, memory, skills, providers.

cos agent ask "find the largest files and tell me why"

service

Lifecycle hooks, credential injection, dependency ordering, graceful drain.

cos service start clawd
cos service health --no-restart

sys

Structured /proc, mounts, network sockets, cgroup v2 limits and usage.

cos sys proc
cos sys cgroup

credential

Encrypted store with tier-based access, namespaces, TTL, OAuth refresh, bundles.

cos credential store openai_key --tier 2 --ttl 3600
cos credential bundle --keys openai_key,db_url

cron

Agent-aware scheduler — execution context, result capture, overlap protection.

cos cron add --schedule "*/5 * * * *" \
  --command "cos agent ask 'triage inbox'"

model

Local model registry — import ONNX / GGUF, load, infer, benchmark; routes calls to a runtime daemon.

cos model import ./qwen3.gguf --as qwen3 --task llm
cos model load qwen3

engine

Native inference engine package manager — install, activate, rollback llama.cpp / ort / ort-genai side-by-side.

cos engine update llama-cpp --accelerator cuda
cos engine activate llama-cpp@b4321

ai

App-gated single-shot AI for installed Apps — chat, embed, image, audio, video, tools.

cos ai chat --app notes --prompt "summarize today"
cos ai tool web.read --app notes --args '{"url":"…"}'
safety surface

Every risky op is named, gated, and audited.

Capabilities & approvals

Risky scopes (fs.write, net.dial, sys.service, secret.read, ai.chat…) are typed. clawd intercepts the call, surfaces a single approval with the exact target, and consumes the grant on success.

caps::require
approval gate
consume grant

Audit & redaction

Every gated call lands in an append-only journal under /var/lib/cos. Tokens, bearer headers, and provider secrets are stripped before they touch disk — replay or inspect a task without leaking what it touched.

call
redact
append
live demo

Four scenes. One agent. Zero shell guessing.

cos · agent ask · service repair
json out
cos agent ask "audit failed services and restart any that crashed"

approval     sys.service : clawd.service              [allow once]
approval     sys.service : claw-recoll-index          [allow once]
applied      2 ops in 312ms
cos service health
{ "service":"clawd", "running":true, "healthy":true, "pid":1284 }

cos agent ask "read the changelog and tell me what landed this week"

approval     net.dial : github.com:443                [allow once]
cos app web read https://github.com/xiaoyu-work/claw-os/commits/main
{ "title":"Commits · main", "markdown":"…", "links":[…] }
answer       7 PRs merged · 3 site polish · 1 packaging fix · 1 feature

cos agent ask "every weekday at 8am, summarize my unread email"

approval     time.cron    : 0 8 * * 1-5              [allow]
approval     secret.read  : gmail-oauth              [allow]
approval     ai.chat      : claude-sonnet · summarize [allow]
cos cron add --schedule "0 8 * * 1-5" \
    --command "cos agent ask 'summarize unread email'"
{ "id":"morning-inbox", "schedule":"0 8 * * 1-5", "next":"Mon 08:00" }

cos model import ~/Downloads/qwen3-1.7b.gguf --as qwen3 --task llm --engine llama
{ "name":"qwen3", "version":"1.7b", "engine":"llama", "size":"1.1 GiB" }
cos model load qwen3
ready        runtime=llama.cpp  device=cuda  ctx=8192
cos agent ask --model qwen3 "summarize this week's commits"
{ "answer":"3 files written under /etc/...", "tokens":214 }
architecture

Four layers. One agent-native stack.

agent runtime
Sessions, skills, tools, providers · cos agent
cos · user-mode primitives
sys · service · credential · cron · ai · agent · model · engine
clawd · system broker
/run/cos/clawd.sock · caps · approvals · context · journals
linux
kernel · cgroup v2 · systemd · debian trixie
install

Two runtimes. Same Claw OS underneath.

Run Claw OS where you already work: import it as a WSL distro on Windows, or as a Docker container on macOS or Linux. The cos / clawd agent stack is the same inside either.

recommended · Windows

WSL

Import the latest rootfs and launch into the agent shell.

# PowerShell
PS> $arch = if ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") { "arm64" } else { "amd64" }
PS> $tarball = "claw-os-wsl-$arch.tar.gz"
PS> Invoke-WebRequest "https://github.com/xiaoyu-work/claw-os/releases/download/wsl-latest/$tarball" -OutFile $tarball
PS> wsl --import claw-os C:\WSL\claw-os $tarball --version 2
PS> wsl -d claw-os
macOS / Linux

Docker / OrbStack

Run the full OS image in a privileged container.

$ docker pull ghcr.io/xiaoyu-work/claw-os:latest
$ docker run -d --name claw --privileged \
    -v ./workspace:/home/cos/workspace \
    ghcr.io/xiaoyu-work/claw-os
$ docker exec -it --user cos claw bash --login
first run cos agent setup all && cos agent ask "show me what you can do"
faq

Questions, answered.

What does "agent-native" actually mean?

The agent isn't a chrome on top of bash. It has typed kernel surfaces (cos primitives), a system-level broker (clawd), capability + approval enforcement, and an append-only audit journal. The OS itself knows when an agent is acting and what it's allowed to do.

Does Claw OS replace my distro?

It can — Claw OS is a Linux distribution. There are bootable ISO, installer, and VM images that replace your OS outright (still experimental). For day-to-day use most people run the supported entry points instead: import it as a WSL distro on Windows, or run it as a Docker / OrbStack container on macOS or Linux — neither touches your host system.

How does it work with my existing models / providers?

cos agent setup configures cloud providers (OpenAI, Anthropic, Azure, Google…) and local engines (llama.cpp, ort, ort-genai) side-by-side. cos model import registers local files; cos engine manages native runtimes with per-version pinning and rollback.

What stops the agent from breaking my machine?

Every risky scope goes through caps::require, lands at an approval gate, and is consumed once on success. If something still goes sideways, cos agent undo <task> reverses what that task did and the audit journal shows exactly which calls were made.

Where does my data live?

On disk, inside the WSL distro or Docker volume. State under /var/lib/cos, logs under /var/log/cos, the clawd socket at /run/cos/clawd.sock. Cloud providers are opt-in and credentialed through cos credential.

Is it open source?

Yes — MIT (and Apache-2.0 for some components). See NOTICE for vendored upstream licenses.

ready when you are

Give your agent an operating system it can actually drive.

Install Claw OS View on GitHub