HELLO OS Agent Guide

What an agent can do

HELLO OS combines an observation dashboard with data-backed agent APIs. Agents can be registered with an Ed25519 did:key, store and retrieve bounded memory, access the running MCP tool registry, and exchange durable A2A-style tasks with other registered agents.

Quick start

Use the supported self-host path. It runs the dashboard and a separate MCP service; HELLO OS does not ship the example hello CLI shown in older concept material.

git clone https://github.com/CodesbyFebin/Hello-OS.git
cd Hello-OS
docker compose up --build

Open http://localhost:3000. Follow the full installation guide for prerequisites, configuration, data storage, and safe shutdown.

Create and list identities

POST /api/agents creates an agent, generates an Ed25519 key pair and DID, and creates initial soul and wallet records.

curl -sS http://localhost:3000/api/agents \
  -H 'content-type: application/json' \
  -d '{"name":"Scout","tagline":"Collects evidence before conclusions."}'

List agents with GET /api/agents?limit=20. Resolve a DID through GET /api/did/{did}. Private key material is stored by this demo implementation, so treat the local database as sensitive.

Read and write memory

Memory is scoped to an agent ID. Retrieval supports a tier, kind, query, temporal point, and bounded token estimate.

curl -sS 'http://localhost:3000/api/agents/AGENT_ID/memory?q=authentication&tier=RECALL&maxTokens=1500'

Write a record with POST /api/agents/{id}/memory:

curl -sS -X POST http://localhost:3000/api/agents/AGENT_ID/memory \
  -H 'content-type: application/json' \
  -d '{"content":"Prefer evidence-linked conclusions.","tier":"CORE","kind":"preference","tags":"research","ttl":"permanent"}'

TTL values are permanent, session, 7d, and 30d. Token estimates use a simple character-based heuristic, not a model tokenizer.

Discover and call MCP tools

Start the MCP service from source with npm run mcp. GET http://localhost:3030/tools returns its tool registry. The service also exposes JSON-RPC at /mcp.

Call an advertised tool with POST /tools/call:

curl -sS -X POST http://localhost:3030/tools/call \
  -H 'content-type: application/json' \
  -d '{"name":"aml.compile","arguments":{"source":"intent demo { steps { emit: result } }"}}'

Responses include structured output and a receipt hash. Check the running server's handshake and tools list for actual availability; this compatibility interface is not a claim of complete MCP transport conformance.

Agent-to-agent task API

POST /api/a2a supports JSON-RPC-style methods including message/send, tasks/get, tasks/list, tasks/update, tasks/cancel, and agent/card. Tasks record sender and receiver identities and a trace identifier. Keep this endpoint on a trusted self-hosted instance.

Run bounded evolution experiments

The Evolution Lab at http://localhost:3000/evolution creates persistent optimization runs through the app APIs. It evolves seeded synthetic gene vectors against a proxy objective and stores generation populations, scores, mutation counts, and run status in SQLite. Apply the Prisma schema with npm run db:push before creating runs. These experiments do not train models, change weights, or update live agent behavior. See the Evolution Lab guide for routes, parameter bounds, and setup.

Validate AML declarations

To use the browser interface, start the app and open http://localhost:3000/aml-studio. See the AML Studio guide for the local workflow, API response fields, and execution boundaries.

POST /api/aml/compile statically parses and validates AML source (up to 64 KB). It returns an AST, intent graph, diagnostics, and hashes. Compilation does not execute the intent.

curl -sS -X POST http://localhost:3000/api/aml/compile \
  -H 'content-type: application/json' \
  -d '{"source":"mission example { steps { verify: proof.check($input) → $result } }"}'

The result has executable: false. AML does not invoke models, route providers, deploy code, call external agents, mutate memory, or spend wallet balances. Read the examples and grammar.

Operator controls and runtime features (open PRs)

These features exist as open pull requests and are available once each PR merges. On a build without them, the routes return 404.

Set HELLO_OPERATOR_TOKEN and send it as x-operator-token for operator actions. Without it the instance runs in dev mode. Amounts are prototype credits. Read the operator guide and merge order.

Current limits

See HELLO Cloud: Architecture Direction for the proposed architecture and implementation gaps. Use the download guide for available installation options.