https://github.com/joncik91/aaos
An agent-first runtime where AI agents are native processes, capabilities replace permissions, and the system is designed for autonomy — not human interaction.
https://github.com/joncik91/aaos
agent-orchestration ai-agents audit-trail capability-based-security human-in-the-loop mcp operating-system rust
Last synced: about 1 month ago
JSON representation
An agent-first runtime where AI agents are native processes, capabilities replace permissions, and the system is designed for autonomy — not human interaction.
- Host: GitHub
- URL: https://github.com/joncik91/aaos
- Owner: Joncik91
- License: apache-2.0
- Created: 2026-03-21T16:23:25.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-25T14:26:44.000Z (about 1 month ago)
- Last Synced: 2026-04-25T14:29:06.781Z (about 1 month ago)
- Topics: agent-orchestration, ai-agents, audit-trail, capability-based-security, human-in-the-loop, mcp, operating-system, rust
- Language: Rust
- Homepage:
- Size: 10.9 MB
- Stars: 3
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
- Roadmap: docs/roadmap.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# aaOS
[](https://github.com/Joncik91/aaOS/actions/workflows/ci.yml)
**A capability-based agentic terminal. Type `aaos`, type a goal, watch the agent work — confined.**
aaOS runs LLM agents as kernel-confined processes: every tool call is gated by an unforgeable capability token, file access is bounded by Landlock, and every approval is an inline keystroke you see and decide. Same shape as Claude Code, Cursor, Codex — but the agent can't read `~/.ssh/id_rsa` even if its prompt is injected.
## Install
```bash
# Debian 13 / Ubuntu 24.04+
wget https://github.com/Joncik91/aaOS/releases/download/v0.4.4/aaos_0.4.4-1_amd64.deb
sudo apt install ./aaos_0.4.4-1_amd64.deb
```
## Run
```bash
aaos
```
First run prompts for a DeepSeek or Anthropic API key (saved to `~/.config/aaos/env` mode 0600), spawns the daemon as a user-level process, and opens the multi-pane TUI. Subsequent runs just open the TUI.
Type a goal in the bottom textarea, hit Enter:
```
┌──────────────────┬─────────────────────────────────┬─────────────────┐
│ plan │ stream │ file │
│ │ │ │
│ ▶ analyse │ [worker] tool: file_read │ 1 # config │
│ ├─ fetch_hn ✓ │ args: path=/etc/os-release │ 2 … │
│ └─ fetch_lobs │ out: PRETTY_NAME="Debian…" │ │
│ └─ writer │ │ │
│ (running) │ [daemon] tool: file_write │ │
│ │ ▲ APPROVAL REQUIRED │ │
│ │ [a]pprove [d]eny │ │
├──────────────────┴─────────────────────────────────┴─────────────────┤
│ > fetch HN top 5 stories and summarize to /tmp/summary.txt │
└───────────────────────────────────────────────────────────────────────┘
```
Watch the Planner emit a DAG into the left pane (status glyphs update live), see tool-calls stream as bordered blocks in the centre with `[worker]`/`[daemon]` execution tags, approve `[a]`/`[d]` when the agent asks to write a file, get a live preview of touched files in the right pane. SSH-renderable; works over plain SSH.
## Subcommands
| Command | What it does |
|---|---|
| `aaos` | Launch the agentic TUI (default) |
| `aaos submit ""` | One-shot headless goal; stream events to stdout, exit |
| `aaos exec -- [args]` | Confine a single command under Landlock (the wedge — works without a daemon) |
| `aaos list` / `status` / `stop` / `logs` | Daemon and agent control |
| `aaos configure` | (Re)write the API key |
| `aaos roles` | List configured roles |
## What's confined, and how
- **Capability tokens, not permissions.** An agent declares capabilities in its YAML manifest (e.g. `file_read: /data/*`). At spawn time the runtime issues unforgeable handle-opaque tokens. Every tool invocation is checked against the caller's tokens before execution. Children inherit only a subset of what the parent holds.
- **Kernel-enforced sandboxing.** When `AAOS_DEFAULT_BACKEND=namespaced`, each agent's tool calls execute inside per-agent Linux user/mount/IPC namespaces with [Landlock](https://landlock.io/) + seccomp active. The capability tokens are forwarded across a broker stream to the worker; tool execution happens in the sandbox. Verified end-to-end on Debian 13 / kernel 6.12.
- **Inline approval moments.** Tools declared `approval_required` in the manifest (default: `file_write`) pause the agent and surface a yellow-bordered block in the TUI's stream pane. Single keystroke resolves it. No "auto-approve" mode.
- **`aaos-exec` — Sudo for AI.** A standalone single-binary CLI (~200 LoC) that wraps any shell command in a Landlock sandbox driven by a one-line YAML policy. Works without a daemon. See [`crates/aaos-exec/README.md`](crates/aaos-exec/README.md).
The kernel does the saying-no. There's no policy server to negotiate with, no system prompt to override.
## Provider support
DeepSeek, Anthropic, any OpenAI-compatible API. Switch via the env file at `~/.config/aaos/env`; restart with `aaos stop && aaos`.
## Build from source
Debian 13 with `cargo` + `cargo-deb` + `pandoc`:
```bash
git clone https://github.com/Joncik91/aaOS.git
cd aaOS
./scripts/setup-hooks.sh
./packaging/build-deb.sh # → target/debian/aaos_*.deb
```
Per-binary `cargo install`:
```bash
cargo install --path crates/aaos # the dispatcher (just `aaos`)
cargo install --path crates/aaos-exec # the wedge (no daemon)
cargo install --path crates/aaos-harness # the TUI directly
cargo install --path crates/agentd # the daemon
```
## Architecture, in one paragraph
`agentd` is a Rust daemon where AI agents are first-class processes. The runtime issues capability tokens at spawn, mediates every tool call through the `Tool` trait, and forwards capabilities to per-agent namespaced workers across a broker stream. The `AgentServices` trait is the substrate-agnostic ABI: process-backed today via `InProcessBackend` and `NamespacedBackend`, MicroVM-per-agent later, microkernel only on a buyer's gating requirement. `aaos-harness` is a Ratatui TUI that drives `agentd` over its existing JSON-RPC + audit-stream surface — *zero* daemon-protocol changes were needed to add it. The full stack: [`docs/architecture.md`](docs/architecture.md).
## Documentation
- **[How it got here](docs/HISTORY.md)** — 60-second walk through the journey, March 2026 → today
- **[Architecture](docs/architecture.md)** — stack, capability model, backends, audit trail, surfaces
- **[Roadmap](docs/roadmap.md)** — what's next (M1 = wedge smoke test, M2 = Debian derivative deferred, R1 = isolation ladder)
- **[Build history](docs/build-history.md)** — long form, 38 entries
- **[Reflection log](docs/reflection/README.md)** — runs where aaOS reads its own code and proposes changes
- **[Patterns](docs/patterns.md)** — cross-cutting lessons distilled from the log
- **[Ideas](docs/ideas.md)** — deferred work + signals to reconsider
- **[Tools](docs/tools.md)** — built-in tool catalog with capability requirements
- **[API](docs/api.md)** — JSON-RPC method reference
- **[CHANGELOG](CHANGELOG.md)** — per-release detail
- **[SECURITY](SECURITY.md)** — threat model, scope, reporting
## License
[Apache License 2.0](LICENSE)