# Home beacon — your PC as a warp target (Panini-shaped commands)

**Goal:** A process on **your machine** speaks the same **`POST /warp/command`** JSON as [`../warp_command_contract/warp_command_schema.json`](../warp_command_contract/warp_command_schema.json). Tool dispatch is a **registry** (no giant `if` chain) — aligned with the **potential** layer in [../../README.md#function-form-potential](../../README.md#function-form-potential) and the same Pāṇini / Daemon DNA (`tap` / `voice`) the vault keeps as future-facing design work.

**Security:** This is **not** “open to the world without auth.” You **must** set **`BEACON_TOKEN`** and expose the service only via **Tunnel / Funnel** + HTTPS, or bind to **localhost** and tunnel out.

**Live edge note:** this keeps the JSON command shape alive as a **local / potential** lane. The current `u-os.dev` Worker contract remains the key-first surface in [../worker/README.md](../worker/README.md).

---

## 1. Run locally (loopback only)

```powershell
cd path\to\vault\08_Project_Astronomicon\u_os_dev\home_beacon
pip install -r requirements.txt
$env:BEACON_TOKEN = "long-random-secret"
$env:BEACON_ROOT = "C:\path\to\your\export_or_vault_root"
python home_beacon.py
```

Default: `http://127.0.0.1:8787` — **not** reachable from the internet until you tunnel.

**Health:** `GET http://127.0.0.1:8787/health` (no auth).

**Command:** `POST http://127.0.0.1:8787/warp/command` with header `Authorization: Bearer <BEACON_TOKEN>` and JSON body like [`../warp_command_contract/sample_request.json`](../warp_command_contract/sample_request.json).

**Allow-listed tools (v0):**

| `tool` | Purpose |
|--------|---------|
| `lab.read` | `args.path` relative to `BEACON_ROOT`; returns text (capped). |
| `eventlog.append` | `args.line` or `args.message` or `args.entry` → JSON lines in `BEACON_LOG`. |
| `beacon.ping` | Sanity check. |

Add more handlers in `REGISTRY` in `home_beacon.py` — same pattern as Daemon **mechanism registry**.

---

## 2. Light the beacon — expose to the internet (pick one)

### A. Cloudflare Tunnel (fits u-os.dev on Cloudflare)

1. Install [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/).
2. Authenticate and create a tunnel; map a hostname (e.g. `beacon.u-os.dev`) to `http://127.0.0.1:8787`.
3. Keep **`BEACON_HOST=127.0.0.1`** so nothing listens on all interfaces without the tunnel.
4. **TLS** terminates at Cloudflare; origin stays HTTP on localhost.

**Any AI** that can **HTTP POST** (agents, scripts, your Worker **proxying** to home) uses:

- `https://beacon.u-os.dev/warp/command`
- Header: `Authorization: Bearer <BEACON_TOKEN>`
- Body: JSON per schema.

**Rotate** `BEACON_TOKEN` if it leaks; prefer **short-lived** tokens later (not implemented in v0).

### B. Tailscale Funnel / Serve

If you use Tailscale: enable **Funnel** or **HTTPS serve** for your tailnet machine, pointing at `127.0.0.1:8787`. You get a public URL on `*.ts.net`. Same Bearer auth.

### C. Do **not** (unless you know what you’re doing)

- Raw **port forward** from your router to the beacon without TLS + strong auth + rate limits.

---

## 3. How “any AI” writes

1. **Document** the public URL + that auth is **Bearer** + point to **`warp_command_contract/warp_command_schema.json`** and **`warp_command_contract/sample_request.json`**.
2. **Agents** with `web_fetch` / `curl` / HTTP tool: `POST` with JSON body.
3. **Optional bridge:** Cloudflare Worker on u-os.dev **`POST /home/proxy`** (you implement) that forwards to the tunnel URL with **server-side** secret — so client AIs never hold `BEACON_TOKEN` (better).

---

## 4. Relation to edge Worker

- **Worker** = always-on, D1, inner Gellar field.
- **Home beacon** = **your** machine, **your** files, **same command shape** — “carried” lab.

Update [`../LAB_ACCESS.md`](../LAB_ACCESS.md) when the URL is live (map only — **no token in git**).

---

*Beacon v0 — extend REGISTRY for `daemon.stress`, git hooks, etc., when you’re ready.*