chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.3.0 Latest 5 packages
title: Running it section: Operations order: 100 summary: The commands that run HUD, the environment variables it reads and the image.
Install the web dependencies, then serve HUD. It listens on port 8787 and serves MCP at /mcp.
Commands
cd web && npm ci && cd ..
just serve # http://localhost:8787, MCP at /mcp
Add http://localhost:8787/mcp to a host that reaches it. For a public deployment, add https://<host>/mcp as a custom connector in Claude.
just dev serves a dev host at http://localhost:5173/dev/. It shows the view as a host would and sends its tool calls to just serve. When the server's sign-in is on, it also plays an MCP client that signs in (dynamic registration, PKCE, the sign-in page in a popup).
An app's own client, such as Grain's (its next/ web shell and ios/ app), lives in its operator's repository, not HUD's. It reaches HUD over /mcp (the operator's views). hud check <dir> checks that app's directory as hud serve would load it, naming every problem, and exits 1 if there's any (checking apps).
just serve also serves the playground at http://localhost:8787/playground, with sign-in on or off. just dev serves it live at http://localhost:5173/playground, its calls sent to just serve.
just local runs HUD against a PDS of its own, to try by hand. It seeds alice, bob and carol (.test, password password) and opens a Chromium window at the workspace. just local --spaces runs it on the spaces alpha, and just local --ios builds the iOS app for a simulator and points it there. Run just local-setup once per checkout and Mac first.
Environment variables
| Variable | Default | |
|---|---|---|
HUD_PORT | 8787 | The port HUD listens on. |
HUD_BIND | :: | The address HUD listens on. |
HUD_PUBLIC_URL | http://localhost:<port> | The origin HUD is reached at. Blob URLs, the view's CSP and sign-in name it. |
HUD_CACHE_DIR | ./cache (/data in the image) | Where HUD keeps resolved lexicons, audio blobs and apps' icons. |
HUD_BLOB_CACHE_BYTES | 2147483648 (2 GiB) | The most bytes of audio HUD keeps in the cache. It evicts the least recently used first. |
HUD_CACHE_MEMORY_BYTES | 67108864 (64 MiB) | About the most bytes the in-memory caches hold together (identities, lexicons, joins' records, counts, feed generators, saved feeds). Each cache gets its share. Past it, HUD drops the expired entries first, then those nearest their end. |
HUD_DATA_DIR | HUD_CACHE_DIR | Where HUD keeps sign-in's client key, sessions and registered clients (under oauth/), the workspace's canvases (under canvas/), each person's theme (under theme/) and, with HUD_LOGS=on, the lines logged (logs.db). Each file has mode 0600. |
HUD_OAUTH | on when HUD_PUBLIC_URL is https, else off | With off there are no sign-in endpoints, no write or canvas tools and no workspace, and HUD makes every call as no one. on needs an https public URL. |
HUD_SPACES | off | With on, HUD keeps each person's canvases in spaces on their own PDS where it offers them and their sign-in allows it (the workspace). HUD then asks for space:place.hud.workspace?authority=*&manage=create&manage=update&manage=delete besides the rest of its scope (what HUD asks for). Publish that space type first, because a PDS refuses every sign-in asking for a type it can't resolve (invalid_scope). It needs sign-in on and the workspace. |
HUD_PLC_URL | https://plc.directory | The PLC directory. |
HUD_HANDLE_RESOLVER | unset | An origin whose com.atproto.identity.resolveHandle resolves handles in place of DNS and /.well-known/atproto-did, such as a local PDS's for tests. |
HUD_ALLOW_PRIVATE | unset | 1 lets outbound requests reach plain http and private addresses. It also reads a did:web of localhost over http, as atproto's own resolver does, for a service run beside HUD such as did:web:localhost%3A2600. Use it for development only. |
HUD_BACKLINKS | constellation:https://constellation.microcosm.blue | The backlink index that counts come from. Set constellation:<url>, or none for no counts. |
HUD_FAVICONS | https://cardyb.bsky.app/v1/favicon?url= | The favicon service HUD asks for apps' icons (/icon/<domain>). HUD adds a site's encoded URL to it, as Bluesky's link cards do. Set and empty, HUD asks nowhere. |
HUD_IMAGE_CDN | https://cdn.bsky.app/img | The image CDN that serves public records' images, at <cdn>/<size>/plain/<did>/<cid>@jpeg (Bluesky's renders any blob on the network). The blob proxy is their fallback. It never serves a space's images, a private answer's images or a GIF. Set and empty, HUD serves every image through the blob proxy. |
HUD_RELAY | https://bsky.network | The relay HUD asks which repositories hold people's workspace themes (com.atproto.sync.listReposByCollection), so a person can browse everyone's. Set and empty, HUD lists only one account's. |
HUD_SIGN_UP_PDS | https://selfhosted.social | The PDS where "Create one" makes a new account, as an origin. HUD asks its authorization server to sign the person up (prompt=create). Details: sign-in. |
HUD_CLIENT_NAME | HUD | The name accounts' servers show for HUD as their OAuth client (its metadata's client_name), as on a PDS's consent screen. The workspace's sign-in page uses it too. An instance that serves one app under that app's name sets it. |
HUD_CLIENT_LOGO | unset | The https URL of the logo accounts' servers show beside that name (logo_uri). |
HUD_APPS | unset | A directory of your own apps (<domain>.json), their views (views/<id>.json) and the lexicons they ship (lexicons/). hud serve and hud resolve read it, and hud check <dir> checks such a directory. HUD trusts those views as it trusts its bundled ones, checks them as it starts and refuses to start if any falls short, naming every problem. A view replaces the bundled one with its id, or that draws what it draws. Details: the operator's views. |
HUD_WORKSPACE | on | With off, HUD serves the apps in HUD_APPS alone, as an app's own front door (Grain's next.grain.social). There's no workspace (/workspace, its methods, the canvas tools), no playground and no bundled view, and / without HUD_WEB is a 404. The methods an app's pages call stay: uploadBlob, searchActors, getLogs, getAccountData and deleteAccountData. Sign-in then asks for what those apps' views do and nothing else (what HUD asks for). off needs HUD_APPS. hud resolve and hud check read it too. |
HUD_WEB | unset | The origin of your own web app, such as http://grain-web:3000, which may be on a private network. HUD hands it /, /favicon.svg, /favicon.ico and every request its own routes don't take, and streams back its answers. HUD checks only that it's an origin as it starts, so it starts and answers /_health before the app is up, and a page it can't reach is a 502. Unset, / goes to the workspace. Details: the web app's pages. |
RUST_LOG | info | What HUD logs, as JSON lines on stderr. A level, or directives such as info,hud::outgoing=debug. Details: observability. |
HUD_SLOW_MS | 1000 | How many milliseconds a request, an outbound call or a tool call takes before HUD logs it at warn. |
HUD_METRICS | unset | A loopback address and port, such as 127.0.0.1:9464, where HUD answers GET /metrics and PUT /log on a listener of their own. HUD refuses any other address. Unset, there's no such listener. |
HUD_LOGS | off | With on, HUD keeps every line it logs in HUD_DATA_DIR/logs.db too, for its operators to read with place.hud.getLogs and admin_logs. |
HUD_LOGS_KEEP | 500000 | How many lines at info and below HUD keeps in logs.db. Any line goes after 30 days. |
HUD_OPERATOR_DIDS | unset | The DIDs of the accounts that run HUD, separated by commas or spaces. They alone read the kept lines. |
The image
Build it with just image (Dockerfile). It runs hud serve as uid 10001 and keeps the cache on the volume /data, so sign-ins and canvases live there too.
Each push to main deploys it to hud.place (.knotless/workflows/deploy.yml). The deploy builds the image on hud.place's box with a cargo cache that's kept between builds, so a deploy compiles only HUD's own crates. Then it swaps the container. The image it replaces stays as hud:before, so you can roll back with docker tag hud:before hud:current and docker compose up -d in /etc/hud.
The iOS app
just ios makes the Xcode project, ios/HUD.xcodeproj, from ios/project.yml. A Release build reaches https://hud.place. A Debug build reaches just serve at http://localhost:8787, or the server its -server <url> launch argument names, which it keeps for later launches.
The app is place.hud.app. Signed out, it asks for a handle and signs in with it (sign-in). Its sign-in comes back to place.hud.app:/oauth/callback, the one redirect the server's client document for it names, so a server and the builds that sign in to it change that together.
The app keeps several accounts signed in to its server and switches between them in Settings. Settings also deletes everything HUD keeps for the account in use (the workspace).
just testflight archives a Release build and uploads it to App Store Connect for TestFlight, as the Apple ID Xcode is signed in with. Raise CURRENT_PROJECT_VERSION in ios/project.yml before each upload, since App Store Connect takes each build number once.
The Android app
android/ is a Gradle project: hudkit, HUD's renderer in Jetpack Compose, and app, the app around it. It needs a JDK 17 and the Android SDK, found by ANDROID_HOME or android/local.properties' sdk.dir.
Its one screen so far is the gallery, the sample tiles just gallery-data writes, as a debug build carries them. just android <entry> installs a debug build on the running emulator and opens it at that entry (just android bsky-thread). A debug build reaches just serve at http://10.0.2.2:8787, which is the Mac as the emulator names it. just android-test runs hudkit's tests on the JVM.