ARK — Agent Runtime Kernel

High-density, stateless, capability-safe runtime kernel for AI agents.

ARK is an open-source library (not a hosted control plane). It schedules many logical agents onto a small pool of warm runtimes, keeps state external, executes tools in-process (no shell), and treats Reset as a security boundary.

RFC source of truth: requirement.txt · Decisions: DECISIONS.md

---

Why ARK?

Problem with container/process agents	ARK approach
Cold start & low packing density	Warm Runtime Pool — M runtimes ≪ N agents
Idle RAM per agent	Agent is data — idle hot memory ≈ 0
Tools via fork/exec	Native Capability (libgit2, search, patch, …)
Unsafe reuse	Reset + probe; failures → tainted
Coupled heap + files	State / Memory / Workspace externalized

Lab result (Apple M3, release): 32 runtimes · 10k idle agents · §20 metrics 17/17 pass · JS snapshot restore ~0.24 ms.
Full write-up: docs/PERFORMANCE.md · Superiority narrative: docs/WHY-ARK.md

---

Documentation

Doc	Content
Architecture	Principles, diagrams, crates, lifecycle
Why ARK	Technical superiority & non-claims
Cloud & load	AWS / GCP / Azure service logic, sizing
Consuming	Embed API, compose with LLM
Performance	Benchmarks vs RFC §20
Contributing	Dev workflow & PR checklist
Security	Multiplex model & reporting

---

Quick start

Library / tests

cargo test --workspace
cargo build --release -p ark-bench && ./target/release/ark-bench

P0 daemon + TUI (macOS / local)

# Start service + open interactive UI
./scripts/arkd-mac.sh ui

# Or step by step
./scripts/arkd-mac.sh start
./scripts/arkd-mac.sh status
./scripts/arkd-mac.sh ui      # ark-tui
./scripts/arkd-mac.sh stop

# Native binary only
cargo run -p arkd -- --data-dir ./data --port 8787
# Docker
docker compose -f deploy/docker-compose.yml up --build

• API: docs/ARKD.md
• Scripts + TUI keys: docs/UI.md

Embed in your service

[dependencies]
ark = { path = "crates/ark" }

use ark::prelude::*;
use std::sync::Arc;

// Build once per process: pool + state + workspace (+ optional isolates / WAL / memory)
// Then: engine.run_once(agent_id, workspace_id, Event::UserMessage { text })?
//    or: engine.run_once_js(...) for JS handleEvent agents
// Result: ExecuteResult { new_state, effects, response }

Details: docs/CONSUMING.md

---

Architecture (one glance)

Product (LLM / Auth / API)
        │ Event
        ▼
   Scheduler (FIFO / Multi-Runtime)
        │
   Runtime Pool ── Isolate Pool (JS)
        │
   State · Memory · Workspace (Base+Overlay)
        │
   Capability Tools (no shell)
        │
   Policy (deny shell · optional seccomp)

Lifecycle: Idle → Acquire → Bind → Execute → Persist → Reset → Idle

---

Status

Phase	Scope	Status
1	Pool, scheduler, state, capability, bench	Done
2	Native tools (search/glob/diff/patch/git/http)	Done (v1 subset)
3	Workspace overlay + base GC	Done
4	JS isolate pool, multi-runtime, policy	Done (boa lifecycle; V8-swappable)

---

Cloud sketch

ARK runs inside your worker. Scale workers on queue depth / pool utilization, not on idle agent count.

• AWS: ECS/EKS + SQS · Dynamo/S3 for state/bases
• GCP: GKE (prefer min instances if Cloud Run — keep pool warm)
• Azure: AKS / Container Apps + Service Bus

Sizing formulas and SLOs: docs/CLOUD.md

---

License

MIT + mandatory attribution（可自由使用，须标注来源）

• 全文：LICENSE · 通知文件：NOTICE

• 允许：使用、修改、分发、商用

• 要求：保留版权与许可证；向第三方分发时标注来源，例如：

  Based on ARK (Agent Runtime Kernel) — https://github.com/21stware/ark

• 源码仓库：https://github.com/21stware/ark