developers

Install the software

Each desktop has a URL that installs it. The script is haus's bootstrap.sh, served plain so it survives a curl | bash, with the desktop written into it:

hacker, everyday and minimal are pinned by their URLs; haus.sh installs the layer and asks instead. The docs explain what a desktop is and what each one builds. A ?ref=v2026.07.18 release tag may be appended to pin the script itself, but nothing published relies on it.

Check a version

Every app on this site ships signed, notarized releases on GitHub. The release endpoint answers with the real latest version, so a download button never hardcodes one:

The JSON carries tag, asset, size, url and publishedAt. The asset URL is also reachable as a stable redirect: download/pounce 302s to the latest DMG, preferring it over the archive the Homebrew formula takes.

Read the documentation as text

The docs under /docs exist in plain-text forms, so a tool can load them without a browser: llms.txt is the index,llms-full.txt is every page's full text, and api/search is the complete search index (Orama JSON, one entry per page section with its URL and breadcrumbs). The MCP server below scores that same index.

Model Context Protocol

/mcp speaks JSON-RPC 2.0 over Streamable HTTP: POST a request, get JSON back. It is stateless (no session ids, nothing to initialize beyond the handshake) and answers with open CORS, so browser-resident agents can call it as well as command-line ones. Point any MCP client at it:

The tools, all read-only over the same public data:

• get_install_command, the one-liner for a desktop; called without a desktop it lists every URL and what it pins.
• get_latest_release, the latest signed macOS release of an app: tag, asset, size, direct download URL, publish date.
• search_docs, full-text search over the docs, returning page URLs, breadcrumbs and excerpts.

Every tool carries explicit read-only annotations, so an agent knows nothing here writes before calling. A docs-only transport serves search_docs alone at /mcp/docs for agents that only want to read, and /mcp.json is the manifest naming both servers.

Search and ask

The REST surface under /v1 serves the same ranked doc search the MCP tool does, cursor-paginated so a crawler can walk the whole result set without guessing shapes:

/v1/desktops, /v1/apps and /v1/releases/pounce round out the surface; every operation has a typed schema in the spec. /ask is the NLWeb-shaped front door: a natural-language query in, ranked excerpts out, JSON by default or text/event-stream when the request asks to stream. Rate limiting is generous and the RateLimit-* headers ride on every response, so an agent can self-throttle by reading, not by being throttled.

Every /v1 data read accepts sandbox=true (the batch and job bodies take "sandbox": true instead), answering with deterministic sample payloads and no live release lookups. It exists for exercising a client against the documented shapes; the rate limit still applies, and nothing on this surface is writable in any mode.

Batch and jobs

An agent acting across the family can bundle reads into one round trip with POST /v1/batch (at most 20 operations, one ok flag per entry). The endpoint accepts an Idempotency-Key header: a retry with the same key within a day is answered from memory with Idempotency-Replayed: true, so a network retry can never double-apply anything. Bigger runs go to POST /v1/jobs, answered 202 with a Location to poll.

Errors, versioning, and auth

Every failure on this surface is RFC 9457 application/problem+json with a machine-readable code; a page that does not exist answers a real 404 with a markdown body pointing agents at the index, not a 200 in disguise. /v1 is path-versioned, and the deprecation policy (a Deprecation: true header plus a Sunset date, announced ahead of it) is written into the spec. There are no credentials: /auth.md is the markdown account of that, and the only supported method is anonymous.

Authenticate a client before its first call

Two well-known documents describe this host's authentication posture to an agent that probes before it calls. /.well-known/oauth-protected-resource is the RFC 9728 Protected Resource Metadata: resource names this host, resource_documentation points at /auth.md, and authorization_servers is empty because no authorization server stands behind the resource. /.well-known/http-message-signatures-directory is the Web Bot Auth directory of Ed25519 keys this host signs responses with; it signs none, so the keys array is empty.

Discovery for agents

A machine that lands here by name, without reading this page first, is answered where it looks: the MCP endpoint also answers at /.well-known/mcp, with its server card at /mcp/server-card and /.well-known/mcp/server-card.json. /.well-known/agent-card.json is the A2A discovery card, /.well-known/agent-skills/index.json lists the domain's agent skills (docs search, install, releases), and /.well-known/api-catalog is the RFC 9727 catalog pointing here. /sitemap.xml is the whole URL list; /schema.jsonl carries the structured data as JSON Lines.

Text over HTML, in three shapes: /index.md (or ?mode=agent, or Accept: text/markdown) is this domain in one markdown page; every docs page has a markdown twin at its own URL plus .md, and a bot User-Agent asking for a docs page is served the twin directly.

Two more name the whole catalog rather than one document. .well-known/ard.json is the Agentic Resource Discovery catalog: both MCP transports, the manifest and the OpenAPI spec. And the repo behind this site is an Agent Plugin: its plugin.json ships the same MCP server as an mcp.json entry, plus a skill covering install and release lookups.

The whole surface, in one file

/openapi.json is the OpenAPI 3.1 description of everything the Worker answers, including the well-known surfaces above. If you are generating a client, generate it from that; this page is the readable half, and the spec is what CI keeps in step with the Worker.