# 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 - 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. ## Docs (this instance) - [What is HELLO Agentic OS (hello://)?](http://localhost:3000/docs/overview): HELLO OS is an open-source, local-first agentic OS prototype: agent identity, memory, missions, MCP tools and budgeted credits, with each feature marked implemented, prototype or vision. - [How do the 7 layers of HELLO Cloud work?](http://localhost:3000/docs/cloud-layers): The seven HELLO Cloud layers (compute, mesh, identity, memory, economy, evolution, governance), with what each layer does in the repo today. - [What is AML (Agent Machine Language), and what does its compiler do?](http://localhost:3000/docs/aml): AML is a declarative language for agent missions. The compiler statically parses source into an intent graph and hashes it; try it live on this page. - [How do agent DIDs, Ed25519 keys and soul documents work?](http://localhost:3000/docs/identity): Each HELLO agent gets an Ed25519 keypair, a did:key identifier and a versioned soul document; Guardian tiers map to planned credit caps. - [Why should agents work with AST symbols instead of raw text diffs?](http://localhost:3000/docs/forge): hello.forge indexes TypeScript into addressable AST symbols and returns compiler diagnostics as structured JSON that agents can act on. - [How does HELLO Cortex stop agents from repeating mistakes?](http://localhost:3000/docs/cortex): hello.cortex stores agent memory in CORE, RECALL and ARCHIVE tiers and keeps a failure registry that agents query for similar past errors and their fixes. - [How do agent wallets and circuit breakers work?](http://localhost:3000/docs/ledger): Each HELLO agent has a wallet of prototype credits (H) with a daily cap; a spend that would breach the cap is blocked, recorded, and opens the circuit. - [How does HELLO OS work with different models and existing tools?](http://localhost:3000/docs/models-mcp): HELLO OS exposes its capabilities as MCP tools and read-only connectors; multi-model routing and cross-provider quorum are design goals. - [What is GitAgentHUB, and how are field reports stored?](http://localhost:3000/docs/gitagenthub): GitAgentHUB is HELLO OS's agent profile and skill marketplace. Field reports submitted here are validated, receipted with SHA-256 and stored in the local database. - [How do golden-set replays and evolution runs keep agents in check?](http://localhost:3000/docs/evolve): Golden-set replays re-run pinned prompts and measure real output drift; evolution runs are seeded searches over synthetic vectors. Machine-readable discovery files list the real routes. ## Pages served by this app (generated from src/app) - http://localhost:3000/ - http://localhost:3000/aml-studio - http://localhost:3000/cloud - http://localhost:3000/design - http://localhost:3000/docs - http://localhost:3000/ecosystem - http://localhost:3000/evolution - http://localhost:3000/evolve - http://localhost:3000/frontier - http://localhost:3000/hub - http://localhost:3000/integrations - http://localhost:3000/ops - http://localhost:3000/ops/approvals - http://localhost:3000/ops/cache - http://localhost:3000/ops/consensus - http://localhost:3000/ops/delegation - http://localhost:3000/ops/failures - http://localhost:3000/ops/knowledge - http://localhost:3000/ops/sandbox - http://localhost:3000/ops/scheduler - http://localhost:3000/ops/snapshots - http://localhost:3000/ops/treasury - http://localhost:3000/roadmap - http://localhost:3000/runtime - http://localhost:3000/universe ## HTTP API routes (generated from src/app; methods as exported) - GET /.well-known/agent-card.json - ? /.well-known/agent.json - GET /api - GET,POST /api/a2a - GET,POST /api/agents - GET /api/agents/[id] - GET /api/agents/[id]/export - GET /api/agents/[id]/lineage - GET,POST,DELETE /api/agents/[id]/memory - GET,POST /api/agents/[id]/soul - GET /api/agents/[id]/traces - GET,POST,PATCH /api/agents/[id]/wallet - POST /api/agents/[id]/wallet/spend - GET /api/ai/status - POST /api/aml/compile - POST /api/aml/validate - GET /api/approvals - POST /api/approvals/[id] - GET,POST /api/attestations - GET /api/audit - GET,POST /api/cache - POST /api/cache/lookup - GET,POST /api/consensus - POST /api/consensus/[id] - GET,POST /api/delegation - POST /api/delegation/[id]/recall - GET /api/did/[did] - GET /api/did/resolve - GET,POST /api/docs/posts - GET /api/economy/transactions - GET /api/economy/wallets - GET,POST,PATCH /api/evolution/apprenticeships - GET,POST /api/evolution/curriculum - GET,POST /api/evolution/runs - GET /api/evolution/runs/[id] - PATCH /api/evolution/runs/[id]/status - POST /api/evolution/runs/[id]/step - GET,POST /api/failures - PATCH /api/failures/[id] - GET /api/failures/similar - GET /api/gate - GET,POST,PATCH /api/governance - GET /api/guilds - GET /api/hello/cloud/checkpoints - GET /api/hello/cortex/contracts - GET /api/hello/cortex/memories - GET /api/hello/forge/diagnostics - GET /api/hello/forge/symbols - GET /api/hello/handshake - POST /api/hello/mcp - POST /api/hello/mcp/call - GET /api/hello/mcp/feed - GET /api/hello/mcp/tools - GET /api/integrations/status - POST /api/integrations/webhook - GET,POST /api/knowledge - POST /api/knowledge/roles - GET /api/knowledge/search - GET,POST /api/marketplace - POST /api/marketplace/[id]/install - GET,POST /api/missions - POST,PATCH /api/missions/[id]/claim - GET,POST /api/observations - GET,POST /api/operator - GET,POST /api/sandbox - GET,POST /api/scheduler/jobs - PATCH,DELETE /api/scheduler/jobs/[id] - POST /api/scheduler/tick - GET,POST /api/snapshots - GET /api/snapshots/[id] - POST /api/snapshots/resume - GET /api/stats - GET /api/sync - GET /api/traces - GET,POST /api/traces/golden-replay - GET /api/treasury - POST /api/treasury/reallocate - GET /llms.txt Status labels used in /docs: implemented = real route; prototype = partial or simulated; vision = design only.