From 12086bd621063f57cb21ac26d75575dc46d77c22 Mon Sep 17 00:00:00 2001
From: Trezy <tre@trezy.com>
Date: Mon, 27 Apr 2026 21:39:53 -0500
Subject: [PATCH] docs: update from localhost to 127.0.0.1 (atrium requirement)

---
 .../docs/docs/getting-started/authentication.md    |  4 ++--
 .../docs/docs/getting-started/configuration.md     |  8 ++++++--
 .../docs/docs/getting-started/deployment/docker.md |  8 ++++++--
 .../docs/docs/getting-started/deployment/other.md  |  6 +++++-
 packages/docs/docs/guides/admin/api-keys.md        |  2 +-
 packages/docs/docs/guides/admin/event-logs.md      |  8 ++++----
 packages/docs/docs/guides/features/api-clients.md  |  2 +-
 packages/docs/docs/guides/features/labelers.md     |  6 +++---
 packages/docs/docs/guides/scripting/batch-save.md  |  2 +-
 .../docs/docs/guides/scripting/cascading-delete.md |  2 +-
 .../docs/guides/scripting/complex-mutations.md     |  2 +-
 .../docs/docs/guides/scripting/create-record.md    |  2 +-
 .../docs/docs/guides/scripting/sidecar-records.md  |  2 +-
 .../docs/docs/guides/scripting/update-or-delete.md |  6 +++---
 .../docs/docs/guides/scripting/upsert-record.md    |  4 ++--
 packages/docs/docs/reference/admin/api-clients.md  |  4 ++--
 packages/docs/docs/reference/admin/api-keys.md     |  6 +++---
 packages/docs/docs/reference/admin/backfill.md     |  4 ++--
 packages/docs/docs/reference/admin/domains.md      |  8 ++++----
 packages/docs/docs/reference/admin/events.md       |  2 +-
 packages/docs/docs/reference/admin/labelers.md     |  8 ++++----
 packages/docs/docs/reference/admin/lexicons.md     | 14 +++++++-------
 packages/docs/docs/reference/admin/plugins.md      |  8 ++++----
 .../docs/docs/reference/admin/script-variables.md  |  2 +-
 packages/docs/docs/reference/admin/settings.md     |  4 ++--
 packages/docs/docs/reference/admin/stats.md        |  2 +-
 packages/docs/docs/reference/admin/users.md        | 12 ++++++------
 packages/docs/docs/reference/xrpc-api.md           | 14 +++++++-------
 packages/docs/docs/tutorials/statusphere.md        | 10 +++++-----
 29 files changed, 87 insertions(+), 75 deletions(-)

diff --git a/packages/docs/docs/getting-started/authentication.md b/packages/docs/docs/getting-started/authentication.md
index 2e63866..195b7b4 100644
--- a/packages/docs/docs/getting-started/authentication.md
+++ b/packages/docs/docs/getting-started/authentication.md
@@ -95,7 +95,7 @@ For automation — CI/CD, monitoring, cron jobs — create an [admin API key](..
 
 ```sh
 export TOKEN="hv_your-api-key-here"
-curl http://localhost:3000/admin/lexicons \
+curl http://127.0.0.1:3000/admin/lexicons \
   -H "Authorization: Bearer $TOKEN"
 ```
 
@@ -196,7 +196,7 @@ For public clients, omit `X-Client-Secret` and include the PKCE challenge in the
 ```
 POST /oauth/dpop-keys
 X-Client-Key: hvc_...
-Origin: http://localhost:3000
+Origin: http://127.0.0.1:3000
 Content-Type: application/json
 
 { "pkce_challenge": "base64url..." }
diff --git a/packages/docs/docs/getting-started/configuration.md b/packages/docs/docs/getting-started/configuration.md
index 634f300..1df104d 100644
--- a/packages/docs/docs/getting-started/configuration.md
+++ b/packages/docs/docs/getting-started/configuration.md
@@ -8,7 +8,7 @@ HappyView is configured via environment variables. A `.env` file in the project
 |----------|----------|---------|-------------|
 | `DATABASE_URL` | yes | --- | Database connection string. SQLite (`sqlite://path/to/db?mode=rwc`) or Postgres (`postgres://user:pass@host/db`) |
 | `DATABASE_BACKEND` | no | auto-detected | Force `sqlite` or `postgres`. Auto-detected from `DATABASE_URL` scheme if not set |
-| `PUBLIC_URL` | yes | --- | Public-facing URL for HappyView (used for OAuth callbacks, e.g. `https://happyview.example.com`) |
+| `PUBLIC_URL` | yes | --- | Public-facing URL for HappyView (used for OAuth callbacks, e.g. `https://happyview.example.com`). **For local development, use `http://127.0.0.1:3000` — not `localhost`** (see note below) |
 | `SESSION_SECRET` | no | dev default | Secret key for signing session cookies (at least 64 characters). **Must be set in production** |
 | `HOST` | no | `0.0.0.0` | Bind host |
 | `PORT` | no | `3000` | Bind port |
@@ -26,12 +26,16 @@ HappyView is configured via environment variables. A `.env` file in the project
 | `TOS_URI` | no | --- | URL to terms of service. Overridden by database setting if set via admin API |
 | `POLICY_URI` | no | --- | URL to privacy policy. Overridden by database setting if set via admin API |
 
+:::warning[Use 127.0.0.1, not localhost]
+ATProto OAuth loopback clients are registered with `127.0.0.1`. If you set `PUBLIC_URL` to `http://localhost:3000`, OAuth sign-in will fail because the redirect URI won't match the loopback client ID. Always use `http://127.0.0.1:3000` for local development.
+:::
+
 ## Example `.env`
 
 ```sh
 # SQLite (default — zero setup required)
 DATABASE_URL=sqlite://data/happyview.db?mode=rwc
-PUBLIC_URL=http://localhost:3000
+PUBLIC_URL=http://127.0.0.1:3000
 SESSION_SECRET=change-me-in-production
 
 # Or use Postgres instead:
diff --git a/packages/docs/docs/getting-started/deployment/docker.md b/packages/docs/docs/getting-started/deployment/docker.md
index ee24418..d111ab2 100644
--- a/packages/docs/docs/getting-started/deployment/docker.md
+++ b/packages/docs/docs/getting-started/deployment/docker.md
@@ -14,7 +14,11 @@ cd happyview
 cp .env.example .env
 ```
 
-Edit `.env` and set at least `PUBLIC_URL` (e.g. `http://localhost:3000`) and `SESSION_SECRET` (at least 64 characters). The defaults work for everything else. See [Configuration](../configuration.md) for the full list of environment variables.
+Edit `.env` and set at least `PUBLIC_URL` (e.g. `http://127.0.0.1:3000`) and `SESSION_SECRET` (at least 64 characters). The defaults work for everything else. See [Configuration](../configuration.md) for the full list of environment variables.
+
+:::warning[Use 127.0.0.1, not localhost]
+ATProto OAuth loopback clients are registered with `127.0.0.1`. If you set `PUBLIC_URL` to `http://localhost:3000`, OAuth sign-in will fail because the redirect URI won't match the loopback client ID. Always use `http://127.0.0.1:3000` for local development.
+:::
 
 ## 2. Start the stack
 
@@ -31,7 +35,7 @@ This starts:
 
 HappyView runs migrations automatically on startup. The first build will take a few minutes while Rust compiles.
 
-The `happyview` container serves its own bundled dashboard at `http://localhost:3000`, but that copy is baked in at container build time and only updates when you rebuild the image. For day-to-day development, use the dev dashboard at `http://localhost:3001` — it hot-reloads on changes to the `web/` source.
+The `happyview` container serves its own bundled dashboard at `http://127.0.0.1:3000`, but that copy is baked in at container build time and only updates when you rebuild the image. For day-to-day development, use the dev dashboard at `http://127.0.0.1:3001` — it hot-reloads on changes to the `web/` source.
 
 :::tip
 SQLite is the default and requires no extra services. To use Postgres instead, uncomment the `postgres` service in `docker-compose.yml` and update `DATABASE_URL` in `.env`. See the [database setup guide](../../guides/database/database-setup.md).
diff --git a/packages/docs/docs/getting-started/deployment/other.md b/packages/docs/docs/getting-started/deployment/other.md
index 55a236f..5eae03a 100644
--- a/packages/docs/docs/getting-started/deployment/other.md
+++ b/packages/docs/docs/getting-started/deployment/other.md
@@ -20,10 +20,14 @@ Edit `.env` to point at your running services:
 ```sh
 # SQLite (default — no setup needed, file created automatically)
 DATABASE_URL=sqlite://data/happyview.db?mode=rwc
-PUBLIC_URL=http://localhost:3000
+PUBLIC_URL=http://127.0.0.1:3000
 SESSION_SECRET=change-me-in-production
 ```
 
+:::warning[Use 127.0.0.1, not localhost]
+ATProto OAuth loopback clients are registered with `127.0.0.1`. If you set `PUBLIC_URL` to `http://localhost:3000`, OAuth sign-in will fail because the redirect URI won't match the loopback client ID. Always use `http://127.0.0.1:3000` for local development.
+:::
+
 Or if you prefer Postgres:
 
 ```sh
diff --git a/packages/docs/docs/guides/admin/api-keys.md b/packages/docs/docs/guides/admin/api-keys.md
index 11f90c8..a5a9655 100644
--- a/packages/docs/docs/guides/admin/api-keys.md
+++ b/packages/docs/docs/guides/admin/api-keys.md
@@ -27,7 +27,7 @@ Each API key has its own set of **scoped permissions**. When you create a key, y
 Pass the key as a Bearer token in the `Authorization` header:
 
 ```sh
-curl http://localhost:3000/admin/lexicons \
+curl http://127.0.0.1:3000/admin/lexicons \
   -H "Authorization: Bearer hv_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
 ```
 
diff --git a/packages/docs/docs/guides/admin/event-logs.md b/packages/docs/docs/guides/admin/event-logs.md
index 274626d..aebd43b 100644
--- a/packages/docs/docs/guides/admin/event-logs.md
+++ b/packages/docs/docs/guides/admin/event-logs.md
@@ -106,16 +106,16 @@ Use the admin API to query event logs with filters:
 
 ```sh
 # Get all errors
-curl "http://localhost:3000/admin/events?severity=error" -H "$AUTH"
+curl "http://127.0.0.1:3000/admin/events?severity=error" -H "$AUTH"
 
 # Get script errors for a specific lexicon
-curl "http://localhost:3000/admin/events?event_type=script.error&subject=com.example.feed.like" -H "$AUTH"
+curl "http://127.0.0.1:3000/admin/events?event_type=script.error&subject=com.example.feed.like" -H "$AUTH"
 
 # Get all lexicon-related events
-curl "http://localhost:3000/admin/events?category=lexicon" -H "$AUTH"
+curl "http://127.0.0.1:3000/admin/events?category=lexicon" -H "$AUTH"
 
 # Paginate through results
-curl "http://localhost:3000/admin/events?limit=20&cursor=2026-03-01T11:59:00Z" -H "$AUTH"
+curl "http://127.0.0.1:3000/admin/events?limit=20&cursor=2026-03-01T11:59:00Z" -H "$AUTH"
 ```
 
 See the [Admin API reference](../../reference/admin/events.md#list-event-logs) for full parameter documentation.
diff --git a/packages/docs/docs/guides/features/api-clients.md b/packages/docs/docs/guides/features/api-clients.md
index 9ebe347..cfdfbe9 100644
--- a/packages/docs/docs/guides/features/api-clients.md
+++ b/packages/docs/docs/guides/features/api-clients.md
@@ -50,7 +50,7 @@ Go to **Settings > API Clients > New client** and fill in:
 ### From the API
 
 ```sh
-curl -X POST http://localhost:3000/admin/api-clients \
+curl -X POST http://127.0.0.1:3000/admin/api-clients \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
diff --git a/packages/docs/docs/guides/features/labelers.md b/packages/docs/docs/guides/features/labelers.md
index 5997b5f..a5ce876 100644
--- a/packages/docs/docs/guides/features/labelers.md
+++ b/packages/docs/docs/guides/features/labelers.md
@@ -22,7 +22,7 @@ HappyView begins consuming labels from the labeler immediately. The subscription
 You can also add a labeler via the API:
 
 ```sh
-curl -X POST http://localhost:3000/admin/labelers \
+curl -X POST http://127.0.0.1:3000/admin/labelers \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{ "did": "did:plc:ar7c4by46qjdydhdevvrndac" }'
@@ -33,7 +33,7 @@ curl -X POST http://localhost:3000/admin/labelers \
 You can pause a labeler subscription to temporarily stop consuming labels without losing your cursor position. Click the pause icon next to the labeler in the table, or use the API:
 
 ```sh
-curl -X PATCH http://localhost:3000/admin/labelers/did:plc:ar7c4by46qjdydhdevvrndac \
+curl -X PATCH http://127.0.0.1:3000/admin/labelers/did:plc:ar7c4by46qjdydhdevvrndac \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{ "status": "paused" }'
@@ -51,7 +51,7 @@ Deleting a labeler removes the subscription **and all labels it has emitted**. T
 Or via the API:
 
 ```sh
-curl -X DELETE http://localhost:3000/admin/labelers/did:plc:ar7c4by46qjdydhdevvrndac \
+curl -X DELETE http://127.0.0.1:3000/admin/labelers/did:plc:ar7c4by46qjdydhdevvrndac \
   -H "$AUTH"
 ```
 
diff --git a/packages/docs/docs/guides/scripting/batch-save.md b/packages/docs/docs/guides/scripting/batch-save.md
index fd363c7..669734a 100644
--- a/packages/docs/docs/guides/scripting/batch-save.md
+++ b/packages/docs/docs/guides/scripting/batch-save.md
@@ -30,7 +30,7 @@ end
 ## Usage
 
 ```sh
-curl -X POST http://localhost:3000/xrpc/xyz.statusphere.batchCreate \
+curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.batchCreate \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
diff --git a/packages/docs/docs/guides/scripting/cascading-delete.md b/packages/docs/docs/guides/scripting/cascading-delete.md
index 398fbae..870868f 100644
--- a/packages/docs/docs/guides/scripting/cascading-delete.md
+++ b/packages/docs/docs/guides/scripting/cascading-delete.md
@@ -55,7 +55,7 @@ end
 ## Usage
 
 ```sh
-curl -X POST http://localhost:3000/xrpc/xyz.statusphere.deletePost \
+curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.deletePost \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
diff --git a/packages/docs/docs/guides/scripting/complex-mutations.md b/packages/docs/docs/guides/scripting/complex-mutations.md
index 93fb46a..94453e2 100644
--- a/packages/docs/docs/guides/scripting/complex-mutations.md
+++ b/packages/docs/docs/guides/scripting/complex-mutations.md
@@ -67,7 +67,7 @@ end
 ## Usage
 
 ```sh
-curl -X POST http://localhost:3000/xrpc/xyz.statusphere.updatePost \
+curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.updatePost \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
diff --git a/packages/docs/docs/guides/scripting/create-record.md b/packages/docs/docs/guides/scripting/create-record.md
index f8c0f94..7b0429e 100644
--- a/packages/docs/docs/guides/scripting/create-record.md
+++ b/packages/docs/docs/guides/scripting/create-record.md
@@ -21,7 +21,7 @@ end
 ## Usage
 
 ```sh
-curl -X POST http://localhost:3000/xrpc/xyz.statusphere.createRecord \
+curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.createRecord \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
diff --git a/packages/docs/docs/guides/scripting/sidecar-records.md b/packages/docs/docs/guides/scripting/sidecar-records.md
index 1d8d8e1..142f752 100644
--- a/packages/docs/docs/guides/scripting/sidecar-records.md
+++ b/packages/docs/docs/guides/scripting/sidecar-records.md
@@ -40,7 +40,7 @@ end
 ## Usage
 
 ```sh
-curl -X POST http://localhost:3000/xrpc/xyz.statusphere.createPost \
+curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.createPost \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
diff --git a/packages/docs/docs/guides/scripting/update-or-delete.md b/packages/docs/docs/guides/scripting/update-or-delete.md
index 981e7aa..ee565df 100644
--- a/packages/docs/docs/guides/scripting/update-or-delete.md
+++ b/packages/docs/docs/guides/scripting/update-or-delete.md
@@ -38,21 +38,21 @@ end
 
 ```sh
 # Create
-curl -X POST http://localhost:3000/xrpc/xyz.statusphere.setRecord \
+curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.setRecord \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{ "status": "hello" }'
 
 # Update
-curl -X POST http://localhost:3000/xrpc/xyz.statusphere.setRecord \
+curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.setRecord \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{ "uri": "at://did:plc:abc/xyz.statusphere.record/abc123", "status": "updated" }'
 
 # Delete
-curl -X POST http://localhost:3000/xrpc/xyz.statusphere.setRecord \
+curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.setRecord \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
diff --git a/packages/docs/docs/guides/scripting/upsert-record.md b/packages/docs/docs/guides/scripting/upsert-record.md
index 020df36..1a1b45c 100644
--- a/packages/docs/docs/guides/scripting/upsert-record.md
+++ b/packages/docs/docs/guides/scripting/upsert-record.md
@@ -41,7 +41,7 @@ end
 
 ```sh
 # Create: no rkey, so a new TID is generated
-curl -X POST http://localhost:3000/xrpc/xyz.statusphere.setStatus \
+curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.setStatus \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
@@ -49,7 +49,7 @@ curl -X POST http://localhost:3000/xrpc/xyz.statusphere.setStatus \
 # → { "uri": "at://did:plc:abc/xyz.statusphere.status/3abc123", "cid": "bafyrei..." }
 
 # Update: pass the rkey back to update the same record
-curl -X POST http://localhost:3000/xrpc/xyz.statusphere.setStatus \
+curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.setStatus \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
diff --git a/packages/docs/docs/reference/admin/api-clients.md b/packages/docs/docs/reference/admin/api-clients.md
index ce2b823..50091bf 100644
--- a/packages/docs/docs/reference/admin/api-clients.md
+++ b/packages/docs/docs/reference/admin/api-clients.md
@@ -24,7 +24,7 @@ GET /admin/api-clients
 Requires `api-clients:view`. Returns clients ordered by `created_at` descending. Secrets are never returned.
 
 ```sh
-curl http://localhost:3000/admin/api-clients -H "$AUTH"
+curl http://127.0.0.1:3000/admin/api-clients -H "$AUTH"
 ```
 
 **Response**: `200 OK`
@@ -60,7 +60,7 @@ POST /admin/api-clients
 Requires `api-clients:create`. Generates a `client_key` and `client_secret`. Store the secret — it won't be shown again.
 
 ```sh
-curl -X POST http://localhost:3000/admin/api-clients \
+curl -X POST http://127.0.0.1:3000/admin/api-clients \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{
diff --git a/packages/docs/docs/reference/admin/api-keys.md b/packages/docs/docs/reference/admin/api-keys.md
index d7544e6..3a34d43 100644
--- a/packages/docs/docs/reference/admin/api-keys.md
+++ b/packages/docs/docs/reference/admin/api-keys.md
@@ -16,7 +16,7 @@ POST /admin/api-keys
 Requires `api-keys:create` permission.
 
 ```sh
-curl -X POST http://localhost:3000/admin/api-keys \
+curl -X POST http://127.0.0.1:3000/admin/api-keys \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{
@@ -53,7 +53,7 @@ GET /admin/api-keys
 Requires `api-keys:read` permission.
 
 ```sh
-curl http://localhost:3000/admin/api-keys -H "$AUTH"
+curl http://127.0.0.1:3000/admin/api-keys -H "$AUTH"
 ```
 
 **Response**: `200 OK`
@@ -83,7 +83,7 @@ DELETE /admin/api-keys/{id}
 Requires `api-keys:delete` permission.
 
 ```sh
-curl -X DELETE http://localhost:3000/admin/api-keys/550e8400-e29b-41d4-a716-446655440000 \
+curl -X DELETE http://127.0.0.1:3000/admin/api-keys/550e8400-e29b-41d4-a716-446655440000 \
   -H "$AUTH"
 ```
 
diff --git a/packages/docs/docs/reference/admin/backfill.md b/packages/docs/docs/reference/admin/backfill.md
index d5bd5f6..3dff0c2 100644
--- a/packages/docs/docs/reference/admin/backfill.md
+++ b/packages/docs/docs/reference/admin/backfill.md
@@ -14,7 +14,7 @@ POST /admin/backfill
 ```
 
 ```sh
-curl -X POST http://localhost:3000/admin/backfill \
+curl -X POST http://127.0.0.1:3000/admin/backfill \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{ "collection": "xyz.statusphere.status" }'
@@ -41,7 +41,7 @@ GET /admin/backfill/status
 ```
 
 ```sh
-curl http://localhost:3000/admin/backfill/status -H "$AUTH"
+curl http://127.0.0.1:3000/admin/backfill/status -H "$AUTH"
 ```
 
 **Response**: `200 OK`
diff --git a/packages/docs/docs/reference/admin/domains.md b/packages/docs/docs/reference/admin/domains.md
index 11750d5..c747564 100644
--- a/packages/docs/docs/reference/admin/domains.md
+++ b/packages/docs/docs/reference/admin/domains.md
@@ -14,7 +14,7 @@ GET /admin/domains
 ```
 
 ```sh
-curl http://localhost:3000/admin/domains -H "$AUTH"
+curl http://127.0.0.1:3000/admin/domains -H "$AUTH"
 ```
 
 **Response**: `200 OK`
@@ -38,7 +38,7 @@ POST /admin/domains
 ```
 
 ```sh
-curl -X POST http://localhost:3000/admin/domains \
+curl -X POST http://127.0.0.1:3000/admin/domains \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{ "url": "https://api.cartridge.dev" }'
@@ -71,7 +71,7 @@ DELETE /admin/domains/{id}
 ```
 
 ```sh
-curl -X DELETE http://localhost:3000/admin/domains/550e8400-e29b-41d4-a716-446655440001 \
+curl -X DELETE http://127.0.0.1:3000/admin/domains/550e8400-e29b-41d4-a716-446655440001 \
   -H "$AUTH"
 ```
 
@@ -88,7 +88,7 @@ POST /admin/domains/{id}/primary
 ```
 
 ```sh
-curl -X POST http://localhost:3000/admin/domains/550e8400-e29b-41d4-a716-446655440001/primary \
+curl -X POST http://127.0.0.1:3000/admin/domains/550e8400-e29b-41d4-a716-446655440001/primary \
   -H "$AUTH"
 ```
 
diff --git a/packages/docs/docs/reference/admin/events.md b/packages/docs/docs/reference/admin/events.md
index 5dbea1f..e7da90a 100644
--- a/packages/docs/docs/reference/admin/events.md
+++ b/packages/docs/docs/reference/admin/events.md
@@ -14,7 +14,7 @@ GET /admin/events
 ```
 
 ```sh
-curl "http://localhost:3000/admin/events?severity=error&limit=10" -H "$AUTH"
+curl "http://127.0.0.1:3000/admin/events?severity=error&limit=10" -H "$AUTH"
 ```
 
 | Param        | Type   | Required | Description                                                           |
diff --git a/packages/docs/docs/reference/admin/labelers.md b/packages/docs/docs/reference/admin/labelers.md
index f423803..eb08ccb 100644
--- a/packages/docs/docs/reference/admin/labelers.md
+++ b/packages/docs/docs/reference/admin/labelers.md
@@ -16,7 +16,7 @@ POST /admin/labelers
 Requires `labelers:create` permission.
 
 ```sh
-curl -X POST http://localhost:3000/admin/labelers \
+curl -X POST http://127.0.0.1:3000/admin/labelers \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{ "did": "did:plc:ar7c4by46qjdydhdevvrndac" }'
@@ -37,7 +37,7 @@ GET /admin/labelers
 Requires `labelers:read` permission.
 
 ```sh
-curl http://localhost:3000/admin/labelers -H "$AUTH"
+curl http://127.0.0.1:3000/admin/labelers -H "$AUTH"
 ```
 
 **Response**: `200 OK`
@@ -71,7 +71,7 @@ PATCH /admin/labelers/{did}
 Requires `labelers:create` permission.
 
 ```sh
-curl -X PATCH http://localhost:3000/admin/labelers/did:plc:ar7c4by46qjdydhdevvrndac \
+curl -X PATCH http://127.0.0.1:3000/admin/labelers/did:plc:ar7c4by46qjdydhdevvrndac \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{ "status": "paused" }'
@@ -92,7 +92,7 @@ DELETE /admin/labelers/{did}
 Requires `labelers:delete` permission. Removes the subscription and all labels emitted by this labeler.
 
 ```sh
-curl -X DELETE http://localhost:3000/admin/labelers/did:plc:ar7c4by46qjdydhdevvrndac \
+curl -X DELETE http://127.0.0.1:3000/admin/labelers/did:plc:ar7c4by46qjdydhdevvrndac \
   -H "$AUTH"
 ```
 
diff --git a/packages/docs/docs/reference/admin/lexicons.md b/packages/docs/docs/reference/admin/lexicons.md
index 6139c79..03a4514 100644
--- a/packages/docs/docs/reference/admin/lexicons.md
+++ b/packages/docs/docs/reference/admin/lexicons.md
@@ -14,7 +14,7 @@ POST /admin/lexicons
 ```
 
 ```sh
-curl -X POST http://localhost:3000/admin/lexicons \
+curl -X POST http://127.0.0.1:3000/admin/lexicons \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{
@@ -48,7 +48,7 @@ GET /admin/lexicons
 ```
 
 ```sh
-curl http://localhost:3000/admin/lexicons -H "$AUTH"
+curl http://127.0.0.1:3000/admin/lexicons -H "$AUTH"
 ```
 
 **Response**: `200 OK`
@@ -73,7 +73,7 @@ GET /admin/lexicons/{id}
 ```
 
 ```sh
-curl http://localhost:3000/admin/lexicons/xyz.statusphere.status -H "$AUTH"
+curl http://127.0.0.1:3000/admin/lexicons/xyz.statusphere.status -H "$AUTH"
 ```
 
 **Response**: `200 OK` with full lexicon details including raw JSON.
@@ -85,7 +85,7 @@ DELETE /admin/lexicons/{id}
 ```
 
 ```sh
-curl -X DELETE http://localhost:3000/admin/lexicons/xyz.statusphere.status -H "$AUTH"
+curl -X DELETE http://127.0.0.1:3000/admin/lexicons/xyz.statusphere.status -H "$AUTH"
 ```
 
 **Response**: `204 No Content`
@@ -101,7 +101,7 @@ POST /admin/network-lexicons
 ```
 
 ```sh
-curl -X POST http://localhost:3000/admin/network-lexicons \
+curl -X POST http://127.0.0.1:3000/admin/network-lexicons \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{
@@ -134,7 +134,7 @@ GET /admin/network-lexicons
 ```
 
 ```sh
-curl http://localhost:3000/admin/network-lexicons -H "$AUTH"
+curl http://127.0.0.1:3000/admin/network-lexicons -H "$AUTH"
 ```
 
 **Response**: `200 OK`
@@ -158,7 +158,7 @@ DELETE /admin/network-lexicons/{nsid}
 ```
 
 ```sh
-curl -X DELETE http://localhost:3000/admin/network-lexicons/xyz.statusphere.status \
+curl -X DELETE http://127.0.0.1:3000/admin/network-lexicons/xyz.statusphere.status \
   -H "$AUTH"
 ```
 
diff --git a/packages/docs/docs/reference/admin/plugins.md b/packages/docs/docs/reference/admin/plugins.md
index d126977..d519b8f 100644
--- a/packages/docs/docs/reference/admin/plugins.md
+++ b/packages/docs/docs/reference/admin/plugins.md
@@ -16,7 +16,7 @@ GET /admin/plugins
 Requires `plugins:read`. Returns every loaded plugin with its source, required secrets, configuration status, and any pending updates from the official registry cache.
 
 ```sh
-curl http://localhost:3000/admin/plugins -H "$AUTH"
+curl http://127.0.0.1:3000/admin/plugins -H "$AUTH"
 ```
 
 **Response**: `200 OK`
@@ -62,7 +62,7 @@ POST /admin/plugins/preview
 Requires `plugins:create`. Fetches and parses a manifest without installing the plugin, so the dashboard can show what it would register.
 
 ```sh
-curl -X POST http://localhost:3000/admin/plugins/preview \
+curl -X POST http://127.0.0.1:3000/admin/plugins/preview \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{ "url": "https://example.com/plugins/steam/manifest.json" }'
@@ -97,7 +97,7 @@ POST /admin/plugins
 Requires `plugins:create`. Fetches the manifest, downloads the WASM, registers the plugin, and persists it.
 
 ```sh
-curl -X POST http://localhost:3000/admin/plugins \
+curl -X POST http://127.0.0.1:3000/admin/plugins \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{
@@ -205,7 +205,7 @@ PUT /admin/plugins/{id}/secrets
 Requires `plugins:create`. Encrypts the provided secret values with `TOKEN_ENCRYPTION_KEY` (AES-256-GCM) and upserts them into `plugin_configs`.
 
 ```sh
-curl -X PUT http://localhost:3000/admin/plugins/steam/secrets \
+curl -X PUT http://127.0.0.1:3000/admin/plugins/steam/secrets \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{
diff --git a/packages/docs/docs/reference/admin/script-variables.md b/packages/docs/docs/reference/admin/script-variables.md
index 4448ae8..66a1df3 100644
--- a/packages/docs/docs/reference/admin/script-variables.md
+++ b/packages/docs/docs/reference/admin/script-variables.md
@@ -24,7 +24,7 @@ POST /admin/script-variables
 Requires `script-variables:create`.
 
 ```sh
-curl -X POST http://localhost:3000/admin/script-variables \
+curl -X POST http://127.0.0.1:3000/admin/script-variables \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{ "key": "ALGOLIA_API_KEY", "value": "..." }'
diff --git a/packages/docs/docs/reference/admin/settings.md b/packages/docs/docs/reference/admin/settings.md
index 19f176a..156f73e 100644
--- a/packages/docs/docs/reference/admin/settings.md
+++ b/packages/docs/docs/reference/admin/settings.md
@@ -14,7 +14,7 @@ GET /admin/settings
 ```
 
 ```sh
-curl http://localhost:3000/admin/settings -H "$AUTH"
+curl http://127.0.0.1:3000/admin/settings -H "$AUTH"
 ```
 
 Returns all key/value pairs stored in the `instance_settings` table.
@@ -26,7 +26,7 @@ PUT /admin/settings/{key}
 ```
 
 ```sh
-curl -X PUT http://localhost:3000/admin/settings/app_name \
+curl -X PUT http://127.0.0.1:3000/admin/settings/app_name \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{ "value": "My HappyView" }'
diff --git a/packages/docs/docs/reference/admin/stats.md b/packages/docs/docs/reference/admin/stats.md
index bc43c8c..32c6e7a 100644
--- a/packages/docs/docs/reference/admin/stats.md
+++ b/packages/docs/docs/reference/admin/stats.md
@@ -12,7 +12,7 @@ GET /admin/stats
 ```
 
 ```sh
-curl http://localhost:3000/admin/stats -H "$AUTH"
+curl http://127.0.0.1:3000/admin/stats -H "$AUTH"
 ```
 
 **Response**: `200 OK`
diff --git a/packages/docs/docs/reference/admin/users.md b/packages/docs/docs/reference/admin/users.md
index 05eac73..87d3317 100644
--- a/packages/docs/docs/reference/admin/users.md
+++ b/packages/docs/docs/reference/admin/users.md
@@ -16,7 +16,7 @@ POST /admin/users
 Requires `users:create` permission. You cannot grant permissions you don't have yourself (escalation guard).
 
 ```sh
-curl -X POST http://localhost:3000/admin/users \
+curl -X POST http://127.0.0.1:3000/admin/users \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{
@@ -53,7 +53,7 @@ GET /admin/users
 Requires `users:read` permission.
 
 ```sh
-curl http://localhost:3000/admin/users -H "$AUTH"
+curl http://127.0.0.1:3000/admin/users -H "$AUTH"
 ```
 
 **Response**: `200 OK`
@@ -80,7 +80,7 @@ GET /admin/users/{id}
 Requires `users:read` permission.
 
 ```sh
-curl http://localhost:3000/admin/users/550e8400-e29b-41d4-a716-446655440000 -H "$AUTH"
+curl http://127.0.0.1:3000/admin/users/550e8400-e29b-41d4-a716-446655440000 -H "$AUTH"
 ```
 
 **Response**: `200 OK` with the same shape as a single item from the list response.
@@ -94,7 +94,7 @@ PATCH /admin/users/{id}/permissions
 Requires `users:update` permission. You cannot grant permissions you don't have yourself, and you cannot modify the super user's permissions.
 
 ```sh
-curl -X PATCH http://localhost:3000/admin/users/550e8400-e29b-41d4-a716-446655440000/permissions \
+curl -X PATCH http://127.0.0.1:3000/admin/users/550e8400-e29b-41d4-a716-446655440000/permissions \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{
@@ -119,7 +119,7 @@ POST /admin/users/transfer-super
 Only the current super user can call this endpoint. Transfers super user status to another existing user.
 
 ```sh
-curl -X POST http://localhost:3000/admin/users/transfer-super \
+curl -X POST http://127.0.0.1:3000/admin/users/transfer-super \
   -H "$AUTH" \
   -H "Content-Type: application/json" \
   -d '{ "target_user_id": "550e8400-e29b-41d4-a716-446655440000" }'
@@ -140,7 +140,7 @@ DELETE /admin/users/{id}
 Requires `users:delete` permission. You cannot delete the super user or yourself.
 
 ```sh
-curl -X DELETE http://localhost:3000/admin/users/550e8400-e29b-41d4-a716-446655440000 \
+curl -X DELETE http://127.0.0.1:3000/admin/users/550e8400-e29b-41d4-a716-446655440000 \
   -H "$AUTH"
 ```
 
diff --git a/packages/docs/docs/reference/xrpc-api.md b/packages/docs/docs/reference/xrpc-api.md
index 0253b94..8fd6644 100644
--- a/packages/docs/docs/reference/xrpc-api.md
+++ b/packages/docs/docs/reference/xrpc-api.md
@@ -22,7 +22,7 @@ GET /health
 ```
 
 ```sh
-curl http://localhost:3000/health
+curl http://127.0.0.1:3000/health
 ```
 
 **Response**: `200 OK` with body `ok`
@@ -36,7 +36,7 @@ GET /xrpc/app.bsky.actor.getProfile
 Returns the authenticated user's profile, resolved from their PDS via PLC directory lookup.
 
 ```sh
-curl http://localhost:3000/xrpc/app.bsky.actor.getProfile \
+curl http://127.0.0.1:3000/xrpc/app.bsky.actor.getProfile \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN"
 ```
@@ -62,7 +62,7 @@ POST /xrpc/com.atproto.repo.uploadBlob
 Proxies a blob upload to the authenticated user's PDS. Maximum size: 50MB.
 
 ```sh
-curl -X POST http://localhost:3000/xrpc/com.atproto.repo.uploadBlob \
+curl -X POST http://127.0.0.1:3000/xrpc/com.atproto.repo.uploadBlob \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: image/png" \
@@ -82,7 +82,7 @@ GET /xrpc/{method}?uri={at-uri}
 ```
 
 ```sh
-curl "http://localhost:3000/xrpc/xyz.statusphere.listStatuses?uri=at%3A%2F%2Fdid%3Aplc%3Aabc%2Fxyz.statusphere.status%2Fabc123" \
+curl "http://127.0.0.1:3000/xrpc/xyz.statusphere.listStatuses?uri=at%3A%2F%2Fdid%3Aplc%3Aabc%2Fxyz.statusphere.status%2Fabc123" \
   -H "X-Client-Key: $CLIENT_KEY"
 ```
 
@@ -114,7 +114,7 @@ GET /xrpc/{method}?limit=20&cursor=<opaque>&did=optional
 | `did` | string | --- | Filter records by DID |
 
 ```sh
-curl "http://localhost:3000/xrpc/xyz.statusphere.listStatuses?limit=10&did=did:plc:abc" \
+curl "http://127.0.0.1:3000/xrpc/xyz.statusphere.listStatuses?limit=10&did=did:plc:abc" \
   -H "X-Client-Key: $CLIENT_KEY"
 ```
 
@@ -148,7 +148,7 @@ POST /xrpc/{method}
 When the body does **not** contain a `uri` field, a new record is created.
 
 ```sh
-curl -X POST http://localhost:3000/xrpc/xyz.statusphere.setStatus \
+curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.setStatus \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
@@ -162,7 +162,7 @@ HappyView proxies this to the user's PDS as `com.atproto.repo.createRecord`, the
 When the body **contains** a `uri` field, the existing record is updated.
 
 ```sh
-curl -X POST http://localhost:3000/xrpc/xyz.statusphere.setStatus \
+curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.setStatus \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
diff --git a/packages/docs/docs/tutorials/statusphere.md b/packages/docs/docs/tutorials/statusphere.md
index 0872f25..675ccb9 100644
--- a/packages/docs/docs/tutorials/statusphere.md
+++ b/packages/docs/docs/tutorials/statusphere.md
@@ -35,7 +35,7 @@ HappyView now subscribes to `xyz.statusphere.status` via Jetstream and kicks off
 You can also add lexicons via the [admin API](../reference/admin/lexicons.md). This is useful for automation or CI/CD workflows:
 
 ```sh
-curl -X POST http://localhost:3000/admin/lexicons \
+curl -X POST http://127.0.0.1:3000/admin/lexicons \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
@@ -84,7 +84,7 @@ Now add a query endpoint to read the indexed data:
 This creates a `GET /xrpc/xyz.statusphere.listStatuses` endpoint. Without a Lua script, it uses HappyView's built-in default behavior: listing records with `limit`, `cursor`, and `did` parameters, or fetching a single record by `uri`. Try it:
 
 ```sh
-curl "http://localhost:3000/xrpc/xyz.statusphere.listStatuses?limit=5" \
+curl "http://127.0.0.1:3000/xrpc/xyz.statusphere.listStatuses?limit=5" \
   -H "X-Client-Key: $CLIENT_KEY"
 ```
 
@@ -140,14 +140,14 @@ end
 The endpoint now uses your custom logic. Filter by a specific user:
 
 ```sh
-curl "http://localhost:3000/xrpc/xyz.statusphere.listStatuses?did=did:plc:abc&limit=1" \
+curl "http://127.0.0.1:3000/xrpc/xyz.statusphere.listStatuses?did=did:plc:abc&limit=1" \
   -H "X-Client-Key: $CLIENT_KEY"
 ```
 
 Fetch a single record by URI:
 
 ```sh
-curl "http://localhost:3000/xrpc/xyz.statusphere.listStatuses?uri=at://did:plc:abc/xyz.statusphere.status/3abc123" \
+curl "http://127.0.0.1:3000/xrpc/xyz.statusphere.listStatuses?uri=at://did:plc:abc/xyz.statusphere.status/3abc123" \
   -H "X-Client-Key: $CLIENT_KEY"
 ```
 
@@ -181,7 +181,7 @@ This creates a `POST /xrpc/xyz.statusphere.setStatus` endpoint that creates reco
 Set a status. This requires DPoP authentication — the [JavaScript SDK](../sdk/overview.md) handles this for you, but you can test with curl if you have a token:
 
 ```sh
-curl -X POST http://localhost:3000/xrpc/xyz.statusphere.setStatus \
+curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.setStatus \
   -H "X-Client-Key: $CLIENT_KEY" \
   -H "Authorization: DPoP $TOKEN" \
   -H "DPoP: $DPOP_PROOF" \
-- 
2.51.2