chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.3.1 Latest 5 packages
0
0
---
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
```sh
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](views.md#the-operators-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](views.md#checking-apps)).
`just serve` also serves [the playground](playground.md) 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](workspace.md)). 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](sign-in.md#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](sign-in.md#creating-an-account). |
| `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](views.md#the-operators-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](sign-in.md#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](internals.md#the-web-apps-pages). |
| `RUST_LOG` | `info` | What HUD logs, as JSON lines on stderr. A level, or directives such as `info,hud::outgoing=debug`. Details: [observability](observability.md). |
| `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](sign-in.md)). 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](workspace.md)).
`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.