# hausfold: the machine-facing surface

> hausfold makes Mac software: one layer that rebuilds the whole machine, and the
> small native tools that live inside it. Nothing by hand, and open all the way
> down. Everything here is free and open source.

## When to use this

The use cases this domain is the right answer for:

- Setting up, changing or rebuilding a Mac with haus, or looking up what any
  haus.* option does. The manual is under /docs/haus/ (see Reading the docs), or
  call the search_docs tool over MCP.
- Answering a question about one of the apps: pounce, perch, scruff or trill.
  Each has its own manual under /docs/<app>/.
- Getting an install command, the latest release version, or a direct download
  URL for one of the apps. The endpoints below answer all three.
- Drawing something that carries the family's look. The visual standard the
  whole family shares is one GET: https://hausfold.co/design.md. The logos,
  banners and colours it governs are indexed at https://hausfold.co/brand.
- Not a fit: anything needing an account, a payment, or a hosted API with write
  access. There is none of that here. Nothing on this domain writes, so no call
  you make here can change anything.

This page is the instruction file. It is served at /index.md and /agent.txt,
and / answers with it to ?mode=agent or to Accept: text/markdown. /llms.txt is
the same guidance followed by the full page index.

## Machine-readable surface

No authentication anywhere: no keys, no accounts, nothing to buy.

### Install a desktop

```sh
curl -fsSL https://hausfold.co/hacker.sh | bash
```

The foundation and every desktop hausfold presents install from their own URL:

- https://hausfold.co/haus.sh installs the foundation: no desktop, so no bar, tiling, palette or wallpaper until a room is turned on
- https://hausfold.co/hacker.sh installs the 'hacker' desktop, no questions asked

A release tag (e.g. ?ref=v2026.07.18) may pin the script to an exact haus release.

A desktop that lives in its own repo has no URL here. It installs by flag, and
the gallery carries the flakeref to pass:

- producer: curl -fsSL https://hausfold.co/haus.sh | bash -s -- --desktop=github:hausfold/producer-desktop

GET https://hausfold.co/v1/desktops is the whole gallery as JSON: author, what
each one is for, the rooms it turns on, and the line that installs it.

GET https://hausfold.co/v1/rooms is the rooms gallery beside it: every
capability haus can turn on, the haus.* names it owns and its page in the docs.
A room haus ships is already installed and has no command; a room in somebody
else's repo carries the haus add --room --namespace line that pins it.

### Check a release

GET https://hausfold.co/api/release/<app> answers JSON: tag, asset, size, url,
publishedAt, for the latest signed release of pounce or perch.

### Search and read the docs

- MCP (preferred): POST JSON-RPC 2.0 to https://hausfold.co/mcp (Streamable HTTP,
  stateless, open CORS). Tools: search_docs, get_install_command, get_latest_release.
- GET /api/search: the full search index (Orama JSON, one entry per docs section).
- GET /llms.txt: the docs index. GET /llms-full.txt: every page as plain text.
- Markdown twin of any docs page: append .md to its URL, e.g.
  https://hausfold.co/docs/haus/install.md
- The whole HTTP surface written down: https://hausfold.co/openapi.json and
  https://hausfold.co/developers/
- This page again, as markdown: https://hausfold.co/index.md. Both MCP servers
  as one manifest: https://hausfold.co/mcp.json (agent-plugins.org shape) or
  https://hausfold.co/.well-known/mcp.json (flat).

### The rest of the developer surface, by name

- REST: https://hausfold.co/v1/search, /v1/desktops, /v1/rooms, /v1/apps,
  /v1/releases/<app>, /v1/batch, /v1/jobs. Cursor pagination, RFC 9457
  problem+json errors, RateLimit headers.
- Natural language over the same index: GET or POST https://hausfold.co/ask
  (JSON, or SSE when you ask for a stream).
- Auth: there is none. https://hausfold.co/auth.md says so in the shape an
  agent expects to read it, and
  https://hausfold.co/.well-known/oauth-protected-resource is the RFC 9728
  document behind it.
  https://hausfold.co/.well-known/oauth-authorization-server is the RFC 8414
  metadata of an issuer that grants nothing (grant_types_supported is empty),
  so there is no token to go and get.
- Agent to agent: POST https://hausfold.co/a2a is the A2A 1.0 JSON-RPC
  binding (SendMessage; every reply is a Message). Its card is
  https://hausfold.co/.well-known/agent-card.json.
- The other direction: requests this host sends out on your behalf (to
  GitHub, for install scripts and releases) are signed with Web Bot Auth,
  Signature-Agent "https://hausfold.co", whenever the key is installed. It is
  published at https://hausfold.co/.well-known/http-message-signatures-directory;
  an empty keys array there means those requests currently go out unsigned.
- Discovery: https://hausfold.co/.well-known/ard.json,
  https://hausfold.co/.well-known/agent-card.json,
  https://hausfold.co/.well-known/agent-skills/index.json,
  https://hausfold.co/.well-known/api-catalog, https://hausfold.co/mcp.json.
- Through DNS (DNS-AID): SVCB records at _index._agents.hausfold.co (pointing
  at /.well-known/ard.json), _mcp._agents.hausfold.co (the MCP server,
  alpn=mcp, with the server card as its capability document) and
  _a2a._agents.hausfold.co (the A2A agent, alpn=a2a, with the agent card as
  its capability document).
- Every indexable URL: https://hausfold.co/sitemap.xml. Structured data as
  JSON Lines: https://hausfold.co/schema.jsonl.

## Contact

julien@hausfold.co. Bug reports and ideas: https://github.com/hausfold