A WINDOW INTO
THE THRONE ROOM.

Quick path

1. Plug the board into a computer with a USB-C data cable.
2. In EmperorClaw, open Settings → Displays → Set up a display in Chrome or Edge and click Connect display.
3. Install the firmware, pick your 2.4 GHz Wi-Fi, click Finish setup. The page says Your display is live.

That is the whole job. Unplug the display and power it from any USB charger. The rest of this guide covers what you are looking at, how your data is protected, and what to do when a step fails.

What you need

Install from the browser

1. Plug in. Connect the display to the computer with the USB-C data cable.
2. Connect. Open Settings → Displays, then click Connect display under Set up a display. Pick the board in the browser’s device list. It shows up as a USB JTAG/serial device.
3. Firmware. The page asks the display which version it runs. If it already has the version your server ships, click Skip — already installed. Otherwise click Install firmware and keep the cable plugged in for about a minute. The page checks every image’s SHA-256 before writing it, and the display’s saved settings are kept.
4. Wi-Fi. The display scans and the page lists the networks it can see, strongest first. Pick yours and type the password. Use Other network for a hidden network name.
5. Options. Name the display (default “Desk display”) so you can find it later, and decide whether to Include my private chats. It is off by default; see Privacy & security.
6. Finish. Click Finish setup. The page creates a read-only key for this display, sends Wi-Fi, server address, and key to the board in one step, and waits. The board restarts, joins Wi-Fi, and fetches the feed. When it reaches the server, the page says Your display is live.

If something goes wrong, the page names the problem: the Wi-Fi password was rejected, the network was not found, joining Wi-Fi timed out, or the server rejected the key. Fix it and click Try again.

What you’ll see

Swipe left or right to change mode. Dots along the bottom edge show which one is active. Each agent is a 12×12 pixel character generated from its id, so the same agent always looks the same, and its body color comes from the agent’s own hue.

Signals in every mode

• Red pulsing rim: at least one agent is down.
• Gold pulsing ring: approvals are waiting for a human.
• Status dot near the top right: green is live, gold is connecting or stale data, red is an error, violet is demo mode.
• Backlight dims after 2 minutes without a touch or a data change, and wakes on either.

Health colors in rings and segments: green healthy, orange attention, red down, blue idle. Before it is configured, the display runs a demo mode with a simulated company of seven agents and a small DEMO tag, so you can check the hardware before any server is involved.

Gestures

Privacy & security

• Read only, really. The display’s key uses the Read only scope. It can call GET /api/mcp/live and nothing else: every other endpoint, the MCP server, and the realtime socket refuse it with 403. Read only keys expire after 365 days.
• Private chats are opt-in, per key. With Include my private chats, the feed adds your own direct exchanges with each agent: messages you wrote and the agent’s replies to you. Other members’ messages are never sent. The option is fixed when the key is created; to change it, revoke the key and set the display up again.
• Tied to you. Every key records who created it. Private chats stop the moment that person leaves the company or is no longer an owner or admin.
• Without the option, private chats never reach the display. An agent busy in one shows only “Working in a private chat”.
• Verified TLS. The display checks the server certificate chain and hostname against the standard public certificate authorities. Plain http:// is accepted only for private-network hosts (10.x, 172.16–31.x, 192.168.x, *.local). The browser setup refuses to run when EmperorClaw itself is opened over http:// on a public address.
• Locked setup Wi-Fi. The on-device setup network uses a random password that appears only on the screen, never in the serial log, so only someone looking at the display can join it. Saved secrets are never shown again or printed.
• Tokens follow the server. Changing the server address without supplying a new token erases the saved one, so a token is only ever sent to the server it was created for.

Managing displays

Settings → Displays lists every display key with its name, when it was created, when it was last used, and whether private chats are on. Click Revoke when a display leaves your desk; it stops updating straight away. To move a display to another network or server, run the setup again. It replaces the saved settings.

Troubleshooting

Without Chrome or Edge

On-device setup portal

1. In EmperorClaw, open Settings → Access Tokens and create a token with the Read only scope. Tick Include my private chats only if you want them. Copy the token.
2. On the display, press and hold for 5 seconds. A ring fills around the edge and the SETUP screen appears.
3. From a phone or laptop, join the Wi-Fi network EmperorClaw-Display with the password shown on the screen. If the setup page doesn’t open, browse to http://192.168.4.1.
4. Pick your Wi-Fi, enter its password, your EmperorClaw address (for example https://emperor.example.com), and the token. Tap Save and connect.
5. The display restarts. The status dot turns green when live data arrives.

Setup gives up after 10 minutes, and tapping the screen cancels it. The portal also offers Run demo mode and Erase settings.

Serial console

At 115200 baud, the display accepts commands such as scan, status, version, ssid, pass, server, token, save, and reset. Developers can build and flash the firmware with PlatformIO from devices/throne-display/ in the repository; the firmware README documents the pin map, the full command set, and the memory design.

For builders: the live feed

The display is just the first consumer. GET /api/mcp/live returns one compact JSON snapshot of your workforce, for any screen or dashboard you want to build. Create a Read only token under Settings → Access Tokens (or POST /api/settings/tokens with "scope": "read_only") and poll it.

curl "https://emperorclaw.example.com/api/mcp/live?messages=8" \
  -H "Authorization: Bearer <read-only-token>" \
  -H 'If-None-Match: "<etag from the last response>"'

Example response, trimmed to one agent:

{
  "v": 1,
  "ts": "2026-10-05T12:00:00.000Z",
  "company": { "name": "Acme" },
  "summary": { "agents": 6, "healthy": 4, "attention": 1, "down": 0, "idle": 1,
               "working": 2, "pendingApprovals": 1, "tasksInProgress": 5, "tasksOverdue": 0 },
  "agents": [
    { "id": "6f1c…", "name": "Ada Researcher", "short": "Ada", "hue": 212,
      "health": "healthy", "state": "typing",
      "activity": "Reading the Q3 report",
      "task": { "id": "9b2e…", "title": "Draft Q3 summary" },
      "lastSeenSec": 12, "unanswered": 0 }
  ],
  "messages": [
    { "id": "c41d…", "from": "Ada", "agentId": "6f1c…",
      "text": "Shipped the Q3 summary", "ageSec": 40 }
  ],
  "dm": []
}

Polling. Every response carries an ETag. Send it back in If-None-Match; when nothing changed you get 304 with an empty body. The ETag ignores the clocks (ts, ageSec, lastSeenSec), so after a 304 add the time since your last 200 to the cached values yourself. Every key is always present, with null for missing values, and v changes only on an incompatible change. The full contract lives in the API reference.