# HELLO OS

> HELLO OS is an experimental, local-first agentic OS prototype with agent identity, persistent memory, missions, an MCP-compatible tool service, A2A-style tasks, and a human dashboard.

## Canonical sources
- Repository: https://github.com/CodesbyFebin/Hello-OS
- Wiki-ready page bundle: https://github.com/CodesbyFebin/Hello-OS/tree/main/docs/wiki
- Community contribution guide: https://github.com/CodesbyFebin/Hello-OS/blob/main/docs/wiki/Community-and-UGC.md
- GitHub Pages machine-readable guide: https://codesbyfebin.github.io/Hello-OS/agents.md
- GitHub Pages project guide: https://codesbyfebin.github.io/Hello-OS/
- Agent guide: https://codesbyfebin.github.io/Hello-OS/agent-guide/
- AML Studio: https://codesbyfebin.github.io/Hello-OS/aml-studio/
- Integration catalog: https://codesbyfebin.github.io/Hello-OS/integrations/
- Machine-readable connector registry: https://codesbyfebin.github.io/Hello-OS/integrations/connector-registry.json
- Machine-readable bridge patterns: https://codesbyfebin.github.io/Hello-OS/integrations/bridge-patterns.json
- Bridge pattern notes: https://codesbyfebin.github.io/Hello-OS/integrations/bridge-patterns.md
- Evolution Lab: https://codesbyfebin.github.io/Hello-OS/evolution-lab/
- HELLO EVOLVE simulation: https://codesbyfebin.github.io/Hello-OS/hello-evolve/
- Installation guide: https://codesbyfebin.github.io/Hello-OS/getting-started/
- Downloads: https://codesbyfebin.github.io/Hello-OS/downloads/
- Architecture direction: https://github.com/CodesbyFebin/Hello-OS/blob/main/docs/hello-cloud-architecture.md
- Security and feature limits: https://github.com/CodesbyFebin/Hello-OS/blob/main/README.md
- Contributor instructions: https://github.com/CodesbyFebin/Hello-OS/blob/main/AGENTS.md

## Verified implementation facts
- The application uses Next.js, React, TypeScript, Prisma, and SQLite; Docker Compose runs the dashboard and a separate MCP service.
- The MCP endpoint is /mcp. Selected tools include forge, cortex, tiered memory, and checkpoint.
- Agent discovery is available at /.well-known/agent-card.json.
- A2A-style JSON-RPC supports message/send and task lifecycle methods.
- AML v1 statically parses and validates declarations at POST /api/aml/compile and POST /api/aml/validate. It builds a deterministic intent graph and hashes source; it never executes AML or invokes tools.
- Evolution Lab stores seeded optimization runs over synthetic vectors. Its proxy scores are not model training or agent benchmarks.
- HELLO EVOLVE is a browser simulation using synthetic demo data.
- The repository is licensed under MIT; see LICENSE.
- GitHub Pages hosts static documentation only; it does not run the Next.js APIs, SQLite database, or MCP service.
- APK, Windows EXE/PEXE, and DEB installers are not currently published.

## Integration catalog status
The catalog contains 100 proposed connector targets and 50 design patterns for legacy bridges. Every connector is marked unconnected and every pattern unshipped. These records are roadmap references, not integrations or vendor endorsements. The running prototype exposes only the capabilities documented in the repository.

## Runtime features in open pull requests (not on main yet)
Each becomes available only once its PR merges. See docs/README.md and docs/merge-order.md in the repository.
- #4 API routes no longer return agent private keys.
- #5 Approval gate with risk tiers, operator kill switch, audit log (/api/approvals, /api/operator, /api/audit).
- #6 Cron-driven heartbeat scheduler (POST /api/scheduler/tick) and a delegation tree with credit caps.
- #7 Integrations registry, 6 read-only MCP connector tools, HMAC webhook bridge (HELLO_WEBHOOK_SECRET, GITHUB_TOKEN, HELLO_MCP_PORT).
- #8 /frontier vision ideas with labelled simulations. #9 Seven-layer card and AML preview with ephemeral demo-key receipts. #10/#16 /runtime live pillar status. #15 /roadmap.
- #11 Sealed checkpoint/resume snapshots and a failure library. #12 Semantic cache with measured hit rate and an RBAC knowledge index. #13 Reputation-weighted debate and gated treasury reallocation. #14 QuickJS WebAssembly sandbox with time and memory limits.
Operator actions require HELLO_OPERATOR_TOKEN when it is set.

## Security and capability limits
This is an experimental prototype, not a hardened production control plane. Demo private keys are stored by the server and are not production-grade key custody. The project does not claim full MCP/A2A conformance, OAuth, SSE, production multi-tenancy, tamper-proof auditing, real-money payments, or Firecracker microVM checkpoints. Wallet balances are prototype credits. No crawler ping, sitemap, or metadata can guarantee search indexing or ranking.

## Start locally
Clone the repository and run docker compose up --build. Open http://localhost:3000. See README.md for prerequisites, configuration, and data handling.