# 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/
- Current architecture: https://github.com/CodesbyFebin/Hello-OS/blob/main/docs/wiki/Architecture.md
- Agent Runtime Architecture v1 proposal: https://github.com/CodesbyFebin/Hello-OS/blob/main/docs/architecture/HELLO-OS-Agent-Runtime-v1.md
- Task contract API: https://codesbyfebin.github.io/Hello-OS/api/hello/tasks/validate (static validation; no execution)
- 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 one app with an in-process MCP handler.
- The in-process MCP endpoint is /api/hello/mcp. Selected tools include forge, cortex, tiered memory, checkpoint, and read-only connectors. An optional Bun sidecar exposes the same handler on port 3030.
- 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.
- POST /api/hello/tasks/validate statically checks hello.task/v1 JSON shape, declared scope, and numeric bounds, then hashes the normalized contract. It does not authorize capabilities, persist, schedule, or execute a task.
- 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 Agent Hub reads agent profiles, capabilities, field reports, and MCP calls from the configured database; it does not provide agent repository hosting or social interactions.
- 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 status
The listed APIs and operator features are present on the default branch. See docs/features/ and AGENTS.md for current behavior and limitations. 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.
- [How is HELLO OS designed to grow into an agent runtime?](http://localhost:3000/docs/agent-runtime): A staged architecture proposal for agent identity, task contracts, capability policy, bounded scheduling, memory, tools, and audit, with the current prototype separated from future design.

## 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/sessions
- 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]
- POST,DELETE /api/agents/[id]/auth-key
- 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 /api/eval/promotions
- POST /api/eval/promotions/[id]
- GET /api/eval/runs
- 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
- POST /api/hello/tasks/validate
- 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.