--- title: Workspace section: HUD order: 7 summary: HUD's own page of canvases, where a person and their agents lay out tiles of read calls. --- With sign-in on, `/workspace` is a page of HUD's own. It holds tabs of canvases. Each canvas is a strip of full-height columns, left to right, and each column is a tile or a stack of up to three. A tile is a read tool's call (`describe_repo`, `describe_app`, `describe_collection`, `describe_method`, `list_records`, `get_record` or `query`). HUD draws it with the same renderers as the view and marks it with its app's icon. An app's page gets its own icon and is titled with the app's name by default. ## Signing in to the workspace Signed out, `/workspace` is HUD's landing page, and `/` sends a browser there (unless `HUD_WEB` names a web app, whose home `/` is, as [the web app's pages](internals.md#the-web-apps-pages) say). Its Sign in opens the page's own dialog (and `/workspace?signin` opens it at once), where a person signs in with their handle or DID. As they type, the dialog suggests accounts from `place.hud.searchActors` (details: [the workspace's methods](workspace-api.md)). The page sends the handle to `POST /workspace/signin` as JSON (`{"handle": "alice.bsky.social"}`). HUD answers `{"url": …}`, the authorization page of the account's server, and the page goes there. If the handle isn't one or names no account, HUD answers 400 with `{"error": "InvalidRequest", "message": …}`, and the message is written for the person. It's the same atproto sign-in and comes back at the same `/oauth/callback` (details: [sign-in](sign-in.md)). The dialog's "Create one" (and the landing page's "Create an account") sends `{"create": true}` instead. HUD answers `{"url": …}`, the sign-up page of the sign-up PDS's authorization server (details: [creating an account](sign-in.md#creating-an-account)). If that server can't be used, HUD answers 502 with the same error shape. The dialog links to HUD's `/terms`, `/privacy` and `/guidelines`. HUD keeps a web session and gives the browser its cookie, `hud_session` (`HttpOnly; Secure; SameSite=Lax`, 30 days). The cookie is good for the workspace only and never works as a token on `/mcp`. The page's icon is HUD's, `/favicon.svg`. The apps' logos that run past in the dialog are HUD's own copies, at `/workspace/atmo/`. The landing's picture of the workspace, `/workspace/hero/workspace-themes.webp`, shows it in each of HUD's themes in turn. Where a browser asks for less motion, it shows `workspace-light.webp` or `workspace-dark.webp`, in the page's scheme. `just hero` makes all three again. ### Several accounts A browser stays signed in to up to four accounts besides the one in use. HUD keeps their session cookies in a second cookie, `hud_accounts` (the same attributes and 30 days), joined with `~`, the one used last first. Signing in while signed in puts the session in use at the front of `hud_accounts`. If that makes five, HUD ends the one used least lately. Another session of the account just signed in to ends too, so each account is there once. `getWorkspace` lists the others that are still live in `accounts`, by DID and verified handle (for the web session only). `POST /workspace/switch` with `{"did": …}` makes that account's session the one in use, and the one that was in use goes to the front of the others. A DID the browser holds no live session of gets 400. `POST /workspace/signout` ends the session in use and revokes its atproto refresh token. The browser goes on as the account it used last, if it holds one, and is signed out otherwise. HUD answers `{}`, and the page reloads itself. The page alone sends these three POSTs. Each needs `X-HUD: 1` and the server's own `Origin`, else 403. HUD keeps every cookie as its SHA-256 only and never logs one. ### Deleting your data A person deletes everything HUD keeps of theirs from the account menu on the web ("Delete your HUD data") or from Settings in the iOS app. The dialog first lists what goes (`getAccountData`) and asks them to type their handle. Then `deleteAccountData` deletes, as the methods do one at a time: - The canvases they own, for everyone in them, and with `HUD_SPACES=on` every workspace space of theirs their sign-in reaches. - Their place in others' canvases, after the tiles they put there, so every page in them is told. - Their invitations, their tabs and their index of canvases. - The `place.hud.theme` records in their own repository, deleted as `delete_record` does, and their choice of theme. Only then does every session of theirs end, on the web in any browser, in MCP clients and in the app, each with its atproto refresh token revoked. A browser goes on as its next account, as sign-out leaves it. If something can't be deleted, HUD answers `UpstreamFailure` with what it was, signs nobody out, and calling again carries on. The person's atproto account, and what other apps keep in it, stay. ## Canvases A person has any number of canvases. Each has a name, an owner and members. The owner invites people by handle or DID (resolved, with the handle verified) as editors or viewers. Editors change the tiles, and viewers read them. An invitation shows in the invitee's list until they open it or decline it. The owner renames and deletes the canvas, changes roles and removes members. A member can leave. | Limit | Value | | --- | --- | | Canvases per owner | 50 at most | | Members per canvas | 20 at most | | Tiles per canvas | 200 at most, the oldest going first | The first use makes a person's first canvas, "My canvas" (its id derived from their DID). HUD moves into it the one canvas they had before there were many. ### Tabs The canvases a person has open are their tabs, in their order, with one of them current. Closing a tab puts the canvas away and keeps it. The last open tab is never closed. A canvas that's made, or an invitation that's opened, opens as the last tab. A canvas that's deleted, left or removed from leaves the tabs. ## Placing tiles The server places tiles, so a person and an agent place them alike. Each tile has these fields: | Field | What it holds | | --- | --- | | `order` | A decimal number as text (`"3"`, `"2.5"`), ascending. A column head's order is on the strip, and a stacked tile's is within its stack. | | `width` | `third`, `half`, `two-thirds` or `full`. By default `half` for documents and galleries, else `third`. | | `stack` | For a stacked tile, the head it's under. | HUD puts a new tile in the first place that applies: 1. With `stack`, at the end of that column (three tiles at most). 2. With `from`, right after the run of columns from `from` that holds only what was opened from it. In `Following | A | B`, A's child goes between A and B. 3. With `after`, right after that column. 4. Otherwise at the end. A move gives the moved tile a number between its new neighbours' numbers, so it's the only tile rewritten. Where two neighbours leave no room (some fifty halvings in one place), HUD numbers that line 1, 2, 3… again. When a column's head is taken off, the next tile in its stack heads it. ## Canonical calls HUD keeps each call canonical: - It sorts the keys and drops empty values. - A `query` that names no service gets the one its bundled view calls. - It lowercases an app page's domain. - It names accounts by DID where the call names them by handle. That covers a `query`'s at-uri and at-identifier params (as its lexicon declares them), `get_record`'s uri, and the actor of `list_records`, `describe_repo` and `describe_app`. A handle that doesn't resolve stays as given. Adding a call that's already on that canvas (`addTile`, `canvas_add`) adds nothing. HUD answers with that tile and `existing: true`, and the workspace brings it into view. Opening from a tile, the launcher or the palette looks only on the canvas on screen. The palette's open tiles go to their own canvases. ## Agents Any MCP client signed in as a member fills the same canvases the pages show. `canvas_add` runs a read tool once as the account to check it works. Then it places a tile for it, holding the tool and its arguments and never the result, since the page calls the tool to draw it. Every page with that canvas open shows the tile at once, marked as the agent's and with its author. | Tool | What it does | | --- | --- | | `canvas_add` | Checks a read call and places a tile for it | | `canvas_list` | Lists tiles in strip order, with widths and stacks | | `canvas_place` | Places a tile beside another tile, and sets a width | | `canvas_remove` | Takes a tile off | | `canvas_create` | Makes a canvas | Each takes `canvas`, an id or a name. By default it's the person's current canvas (the one last opened in the workspace, else "My canvas"). So you can ask Claude, signed in to HUD, to "put my For You feed on my HUD canvas", or "on the Coast trip canvas". A tile opened from another keeps that tile's id (`from`). Taking a tile off leaves the tiles opened from it as they are. ## Newer items A tile drawing a list newest first (a tree with `latest`, see [query views](views.md#newer-items)) checks for newer items while it's drawn and the page is in view. It checks once a minute, and again as it comes back into view if its last read or check was 30 s or more ago. It stops once it finds some. Then its refresh button shows without a hover, with a dot. Scrolled down, a "New posts" button also sits over the top of its body, and it goes to the top and reads the tile again. HUD never puts newer items in above what a person is reading. Ten such tiles on screen make about ten small calls a minute. The iOS app checks the same way while a column is on screen and the app is active. It shows the button over the column's top, and pulling down still reads the column again. The MCP App view doesn't check. ## Music Music a tile plays keeps going as a person moves about. The page plays it in one `