~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
80 lines · 10.3 KB Raw History

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

VariableDefault
HUD_PORT8787The port HUD listens on.
HUD_BIND::The address HUD listens on.
HUD_PUBLIC_URLhttp://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_BYTES2147483648 (2 GiB)The most bytes of audio HUD keeps in the cache. It evicts the least recently used first.
HUD_CACHE_MEMORY_BYTES67108864 (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_DIRHUD_CACHE_DIRWhere 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_OAUTHon when HUD_PUBLIC_URL is https, else offWith 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_SPACESoffWith 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_URLhttps://plc.directoryThe PLC directory.
HUD_HANDLE_RESOLVERunsetAn 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_PRIVATEunset1 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_BACKLINKSconstellation:https://constellation.microcosm.blueThe backlink index that counts come from. Set constellation:<url>, or none for no counts.
HUD_FAVICONShttps://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_CDNhttps://cdn.bsky.app/imgThe 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_RELAYhttps://bsky.networkThe 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_PDShttps://selfhosted.socialThe 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_NAMEHUDThe 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_LOGOunsetThe https URL of the logo accounts' servers show beside that name (logo_uri).
HUD_APPSunsetA 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_WORKSPACEonWith 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_WEBunsetThe 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_LOGinfoWhat HUD logs, as JSON lines on stderr. A level, or directives such as info,hud::outgoing=debug. Details: observability.
HUD_SLOW_MS1000How many milliseconds a request, an outbound call or a tool call takes before HUD logs it at warn.
HUD_METRICSunsetA 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_LOGSoffWith 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_KEEP500000How many lines at info and below HUD keeps in logs.db. Any line goes after 30 days.
HUD_OPERATOR_DIDSunsetThe 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.