# HermesOS

> 

- Documentation: https://hermesos.thally.app
- GitHub: https://github.com/Induj1/hermesosdocs
- Full docs for LLMs: https://hermesos.thally.app/llms-full.txt
- Agent discovery (ai.txt): https://hermesos.thally.app/ai.txt
- Structured docs index (JSON): https://hermesos.thally.app/api/docs-index
- OpenAPI spec: https://hermesos.thally.app/openapi.yaml

## For AI agents

Every page supports content negotiation on its human URL:
- JSON API: append `?format=json` or send `Accept: application/json`
- JSON-LD: append `?format=ldjson` or send `Accept: application/ld+json`
- Markdown: append `?format=md` or send `Accept: text/markdown`
- Per-page API: https://hermesos.thally.app/api/docs/{page-id}
- Search API: https://hermesos.thally.app/api/search?q={query}
- Capability manifest (skill): https://hermesos.thally.app/skill.md
- Agent guidance (editing these docs): https://hermesos.thally.app/AGENTS.md
- MCP server (attach docs as native tools): https://hermesos.thally.app/api/mcp
- Agent readiness: https://hermesos.thally.app/api/agent-readiness

### Recommended workflow

1. Use this index, the search API, or `search_docs` before choosing a page.
2. Read the smallest set of relevant pages and follow their prerequisite links.
3. Treat the published docs as the source of truth. Label inferences and say when evidence is missing.
4. Cite the canonical human page URLs, not only API endpoints.
5. Use `/AGENTS.md` before editing a repository. The public MCP server is read-only.

## Get started

### Start here

- [Introduction](https://hermesos.thally.app/): HermesOS is a composable TypeScript runtime for autonomous AI — a kernel that runs a graph of tasks toward a goal.
- [Quickstart](https://hermesos.thally.app/quickstart): Clone HermesOS, build the workspace, run the test suite, and serve the API.

### Concepts

- [Missions and tasks](https://hermesos.thally.app/concepts/missions-and-tasks): How the kernel turns a goal into a graph of tasks, and what it deliberately refuses to know.
- [Tools](https://hermesos.thally.app/concepts/tools): How a HermesOS tool declares its arguments, its metadata, and what it needs — so a model can call it correctly.
- [Permissions](https://hermesos.thally.app/concepts/permissions): Declare what a tool needs, grant a set at the composition root, and refuse a tool the permissions it was not given.

## Guides

### Build

- [Write a tool](https://hermesos.thally.app/guides/write-a-tool): Declare a tool, give it a schema and permissions, test it the way the kernel calls it, and register it.

### Operate

- [Run the API service](https://hermesos.thally.app/guides/run-the-api): Build and serve the HermesOS API, check that it is healthy, and scrape its metrics.

## Reference

### Reference

- [Tool errors](https://hermesos.thally.app/reference/tool-errors): Every error the HermesOS tool framework throws on purpose, with the stable code you branch on.
- [Package map](https://hermesos.thally.app/reference/packages): Every package in the HermesOS monorepo and what it is responsible for.
- [API overview](https://hermesos.thally.app/api/introduction): The HTTP surface HermesOS exposes, and what each route is for.
- [Troubleshooting](https://hermesos.thally.app/troubleshooting): Diagnose the failures HermesOS reports most often, and what to change in each case.

## API Reference

Interactive API reference available at https://hermesos.thally.app/api