# Reefy - turn any PC into a private AI server

Reefy is an OS for AI computers. Boot from a USB dongle, adopt the
device in your dashboard, run AI agents and LLMs on your own
hardware. No Linux setup required.

Canonical URLs:

- [Homepage](https://reefy.ai/)
- [Dashboard](https://reefy.ai/dashboard)
- [Open source](https://github.com/reefyai/reefy)
- [LLM proxy](https://github.com/reefyai/reefy-llm-proxy)
- [QR-access app](https://github.com/reefyai/reefy-qr-access)
- [X / Twitter](https://x.com/reefy_ai)
- [Product Hunt](https://www.producthunt.com/products/reefy)

## Five-step install

1. Bring a PC. Any x86_64 box with 4 GB+ RAM. Old laptop, mini-PC,
   used NUC, or a high-end server with NVIDIA GPUs all work.
2. Download the Reefy image (~2 GB raw, no signup).
3. Flash to an 8 GB+ USB drive with Balena Etcher / Rufus / dd.
4. Boot the PC from USB (Esc / Del / F12 for BIOS boot menu).
   First boot is ~15 seconds; disable Secure Boot if blocked.
5. Adopt the device. Open https://reefy.ai/dashboard, the new
   device appears automatically once online. Click Adopt, name it,
   install apps.

## Architecture in one paragraph

Reefy OS is built from Buildroot, hand-picked package-up from the
kernel. Immutable A/B root with hardware-watchdog auto-rollback,
LUKS-on-thin-pool encrypted storage keyed to a USB dongle, NVIDIA
GPU drivers baked into the firmware, Cloudflared tunnels for remote
access, EMQX MQTT bridge for the dashboard's real-time updates.
The dashboard at reefy.ai is a Flask + PostgreSQL backend; each
device runs a per-app catalog of containers (OpenClaw, Hermes,
Ollama, vLLM, SGLang, QR-access, etc.).

## What you can do out of the box

- Run private AI agents: OpenClaw, Hermes - multiple isolated
  instances per device, each in its own container.
- Bring your own LLM subscription: OAuth into your OpenAI Codex or
  xAI Grok plan, agents call it through reefy-llm-proxy at
  http://localhost:9080/v1 - no API keys, no per-token billing.
- NVIDIA GPU acceleration out of the box. Drivers ship with the
  firmware. Start Ollama, vLLM, SGLang, or any GPU-aware tool and
  it just works.
- Built-in monitoring: CPU, GPU, memory, disk, network,
  temperatures, fans - charted from the moment you adopt.
- A/B firmware updates with hardware-watchdog auto-rollback. A bad
  update reverts to the previous working version. Safe for closet
  and attic deployments.
- Encrypted cloud backups via BorgBase. Adopt-and-Clone restores
  apps + data on a fresh PC like restoring an iPhone.
- Web terminal that works from desktop or phone, with on-screen
  modifier-key buttons.
- Remote access via Cloudflared tunnels - no port forwarding, no
  VPN, no static IP. Every device gets a public reefy.ai subdomain.
- QR-access app: turn a USB-bootable Reefy device + a Hikvision
  ONVIF camera + a Shelly relay into a self-hosted door-access
  system. YOLOv8 detection + pyzbar decode + Shelly relay control.

## Hardware requirements

- CPU: any x86_64 (Intel or AMD).
- RAM: 4 GB minimum, 8 GB+ recommended for LLM workloads.
- USB: 8 GB+ drive for the boot media. Internal NVMe/SATA used for
  app storage; Reefy auto-detects and provisions.
- GPU: optional. NVIDIA Pascal (GTX 1060) or newer for GPU apps.
  Reefy ships CUDA + driver; no host install needed.
- Network: wired or wifi. Reefy adopts wifi creds on first boot
  via the dashboard.

## Supported apps (built-in catalog)

- **OpenClaw**: open-source local AI agent, with OAuth login to
  OpenAI Codex or xAI Grok subscriptions.
- **Hermes Agent**: Nous Research's open-source agent, with OAuth
  to xAI SuperGrok or OpenAI Codex (via picker in `hermes model`).
- **Ollama**: local LLM inference (Llama, Mistral, Qwen, etc.).
- **vLLM**: high-throughput batched LLM serving.
- **SGLang**: structured-generation LLM serving.
- **QR-access**: door access control via camera + Shelly relay.
- **reefy-llm-proxy**: OpenAI-compatible gateway for BYO
  subscription auth.
- **Custom containers**: any Docker image via the app catalog's
  "Custom App" entry, with isolated volumes + ports.

## Frequently asked

**Is Reefy free?**
Yes. Open source, hosted dashboard is free, runs on hardware you
already own. No per-token costs and no SaaS lock-in.

**How does Adopt-and-Clone work?**
Encrypted backups go to BorgBase (default) or your own restic-
compatible target. On a fresh Reefy device, pick "Restore from
backup" during adoption - apps + data come back in minutes.

**Will a bad firmware update brick my device?**
No. A/B firmware with hardware watchdog: if the new partition
fails to boot, the watchdog reverts to the previous working
version automatically.

**Can I run multiple instances of the same app?**
Yes. Add as many OpenClaw / Hermes / Ollama instances as your
hardware can host. Each runs in its own container with isolated
storage.

**Does Reefy work without an internet connection?**
The OS boots and runs locally; you only need internet for: cloud
backups, the dashboard (which is the control plane), remote
access via Cloudflared, and any LLM-as-a-service apps you install
(local Ollama doesn't need internet after the model downloads).

**How do I get help?**
File a [GitHub issue](https://github.com/reefyai/reefy/issues) or
ping [@reefy_ai](https://x.com/reefy_ai) on X.

## Example: list a user's devices via the OpenAPI spec

The dashboard API is documented at
[/openapi.json](https://reefy.ai/openapi.json). A signed-in agent can
list devices with:

```bash
curl https://reefy.ai/api/devices \
  -H "Cookie: session_id=<browser-session-cookie>" \
  -H "Accept: application/json"
```

Response shape (abridged):

```json
{
  "devices": [
    {
      "uuid": "...", "hostname": "reefy-...", "name": "office-nuc",
      "adopted": 1, "status": "online",
      "instances": [{"app_slug": "openclaw", "host_port": 20001}]
    }
  ]
}
```

See [/auth.md](https://reefy.ai/auth.md) for the OAuth walkthrough.
Bearer-token (PAT) support for headless agents is on the roadmap.

## Example: call the MCP server

```bash
curl https://reefy.ai/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_app_catalog"}}'
```

Tool manifest: [/.well-known/mcp/server-card.json](https://reefy.ai/.well-known/mcp/server-card.json).

## Discovery surfaces for AI agents

- [/llms.txt](https://reefy.ai/llms.txt) - short product summary
- [/llms-full.txt](https://reefy.ai/llms-full.txt) - this file
- [/sitemap.xml](https://reefy.ai/sitemap.xml) - canonical URL list
- [/index.md](https://reefy.ai/index.md) - markdown homepage
- [/openapi.json](https://reefy.ai/openapi.json) - OpenAPI 3.1 spec
- [/ask](https://reefy.ai/ask) - NLWeb-style natural-language Q&A (POST JSON `{"query": "..."}`)
- [/mcp](https://reefy.ai/mcp) - Model Context Protocol JSON-RPC endpoint
- [/agents.md](https://reefy.ai/agents.md) - when-to-use guidance for AI assistants
- [/developers](https://reefy.ai/developers) - developer landing
- [/.well-known/agent-card.json](https://reefy.ai/.well-known/agent-card.json) - A2A Agent Card
- [/.well-known/agent-skills/index.json](https://reefy.ai/.well-known/agent-skills/index.json) - skills index
- [/.well-known/api-catalog](https://reefy.ai/.well-known/api-catalog) - RFC 9727 API linkset
- [/.well-known/mcp/server-card.json](https://reefy.ai/.well-known/mcp/server-card.json) - MCP server card
- [/.well-known/oauth-protected-resource](https://reefy.ai/.well-known/oauth-protected-resource) - RFC 9728
- [/.well-known/oauth-authorization-server](https://reefy.ai/.well-known/oauth-authorization-server) - OIDC discovery
- [/auth.md](https://reefy.ai/auth.md) - agent auth walkthrough