A lexicon-driven AppView for ATProto.
happyview.dev
backfill
firehose
jetstream
atproto
appview
oauth
lexicon
docs: add info about the XRPC proxy
+106
+4
packages/docs/docs/getting-started/dashboard.md
+4
packages/docs/docs/getting-started/dashboard.md
···
83
83
84
84
Configure labeler subscriptions for content labeling. See [Labelers](../guides/features/labelers.md) for details.
85
85
86
+
### XRPC Proxy
87
+
88
+
Control which unrecognized XRPC methods are forwarded to their resolved authority. Choose from four modes: **Disabled** (block all proxy requests), **Open** (proxy everything — the default), **Allowlist** (only proxy NSIDs matching your patterns), or **Blocklist** (proxy everything except matching patterns). Allowlist and blocklist modes accept NSID patterns with trailing wildcards (e.g. `com.example.*`). Locally registered lexicons are always served regardless of this setting. See [XRPC Proxy](../reference/admin/xrpc-proxy.md) for the full API reference.
89
+
86
90
### Environment Variables
87
91
88
92
View the current values of all environment variables that affect HappyView's behavior. This is a read-only view — values are set via your deployment environment, not the dashboard.
+93
packages/docs/docs/reference/admin/xrpc-proxy.md
+93
packages/docs/docs/reference/admin/xrpc-proxy.md
···
1
+
# Admin API: XRPC Proxy
2
+
3
+
Control which unrecognized XRPC methods HappyView forwards to their resolved authority. Locally registered lexicons are always served regardless of this setting.
4
+
5
+
All endpoints require the `settings:manage` permission.
6
+
7
+
```sh
8
+
# All examples assume $TOKEN is an API key (hv_...)
9
+
AUTH="Authorization: Bearer $TOKEN"
10
+
```
11
+
12
+
## Get proxy config
13
+
14
+
```
15
+
GET /admin/settings/xrpc-proxy
16
+
```
17
+
18
+
```sh
19
+
curl http://127.0.0.1:3000/admin/settings/xrpc-proxy -H "$AUTH"
20
+
```
21
+
22
+
**Response**: `200 OK`
23
+
24
+
```json
25
+
{
26
+
"mode": "allowlist",
27
+
"nsids": ["com.example.feed.*", "games.gamesgamesgamesgames.*"]
28
+
}
29
+
```
30
+
31
+
Returns `{"mode": "open", "nsids": []}` when no config has been saved.
32
+
33
+
## Update proxy config
34
+
35
+
```
36
+
PUT /admin/settings/xrpc-proxy
37
+
```
38
+
39
+
```sh
40
+
curl -X PUT http://127.0.0.1:3000/admin/settings/xrpc-proxy \
41
+
-H "$AUTH" \
42
+
-H "Content-Type: application/json" \
43
+
-d '{
44
+
"mode": "allowlist",
45
+
"nsids": ["com.example.feed.*"]
46
+
}'
47
+
```
48
+
49
+
**Response**: `204 No Content`
50
+
51
+
Changes take effect immediately — no restart needed.
52
+
53
+
### Modes
54
+
55
+
| Mode | Behavior |
56
+
|------|----------|
57
+
| `disabled` | Block all proxy requests. Return `403` for every unrecognized NSID. |
58
+
| `open` | Proxy everything (default). Current behavior on a fresh install. |
59
+
| `allowlist` | Proxy only NSIDs matching a pattern in `nsids`. Return `403` for the rest. |
60
+
| `blocklist` | Proxy everything except NSIDs matching a pattern in `nsids`. |
61
+
62
+
When mode is `disabled` or `open`, any `nsids` in the request body are ignored and stored as `[]`.
63
+
64
+
### NSID patterns
65
+
66
+
Patterns are dotted NSID identifiers. Trailing wildcards are supported:
67
+
68
+
- `com.example.feed.getHot` — exact match
69
+
- `com.example.feed.*` — matches any NSID starting with `com.example.feed.`
70
+
- `games.gamesgamesgamesgames.*` — matches the entire namespace
71
+
72
+
Mid-segment wildcards (e.g., `com.*.feed`) are not supported.
73
+
74
+
### Validation errors
75
+
76
+
| Status | Cause |
77
+
|--------|-------|
78
+
| `400` | An NSID pattern is empty, has fewer than two segments, contains invalid characters, or uses an unsupported wildcard |
79
+
| `422` | `mode` is not one of `disabled`, `open`, `allowlist`, `blocklist` |
80
+
81
+
## Blocked request response
82
+
83
+
When the proxy denies a request, the client receives:
84
+
85
+
```
86
+
403 Forbidden
87
+
```
88
+
89
+
```json
90
+
{
91
+
"error": "NSID not allowed by proxy policy"
92
+
}
93
+
```
+4
packages/docs/docs/reference/xrpc-api.md
+4
packages/docs/docs/reference/xrpc-api.md
···
177
177
178
178
**Response** for both: proxied from the user's PDS.
179
179
180
+
## XRPC proxy
181
+
182
+
When a request targets an NSID that has no locally registered lexicon, HappyView resolves the NSID's authority via DNS and forwards the request. Admins can restrict which NSIDs are proxied — see [XRPC Proxy settings](admin/xrpc-proxy.md).
183
+
180
184
## Errors
181
185
182
186
All error responses return JSON with an `error` field: