Skip to content

Inbox: wake a paired cloud agent by its webhook (step 1) - #3138

Merged
backnotprop merged 15 commits into
mainfrom
feat/inbox-cloud-agent-wake
Nov 12, 2026
Merged

backnotprop merged 15 commits into
mainfrom
feat/inbox-cloud-agent-wake

Conversation

@backnotprop

@backnotprop backnotprop commented Nov 11, 2026 •

Copy link
Copy Markdown
Owner

This is step 1 of "Pair a cloud agent": the one-way wake. The Inbox can now wake a Claude Code routine, a Grok Bot routine, or any other webhook when you write to it. The agent can't post back into the thread yet; that comes in later steps. For now it answers where it works, such as a pull request or its own run.

What you see

  • Settings → Devices → Cloud agents → Pair a cloud agent. You pick Claude Code, Grok Bot or Other, then enter a name, the webhook address and the key. With more than one project you also pick where its threads go. Then press Pair.
  • After Pair, you get one block to paste into the routine's instructions, with a Copy button. Send a test fires the webhook once and tells you whether a run started. For Claude it links to the run.
  • The agent shows up in New message's To list and in the sidebar's Agents, with a small cloud mark.
  • Sending or replying to it wakes it. The thread then shows a line such as "Woke Nightly fixer · run started · Open the run". If it waits or fails, the line says that plainly: "Wakes … at 11:50", "did not answer in time…", "is at its hourly limit…", or "refused its key… Paste the new key".

Rules

  • At most one wake per thread per minute. Replies sent inside that minute are held and go together in the next wake.
  • Only a 200 counts as "started" (for Other, any 2xx).
  • A timeout is "uncertain" and is never sent again, because a Claude routine would start a second run. A 5xx retries on the Codex wake's backoff. A 429 waits for its Retry-After. A refused key (401 or 403) waits until you paste a new one.
  • The state is written on the message itself before and after each POST. Every window and device shows the same line, and a restart never resends.
  • Remove unpairs at once and deletes the key. No confirm dialogs, no new keyboard shortcuts.

Secrets

  • The address and the key live only in inbox/cloud-agents.json (0600).
  • They never appear in config.json, an API answer, an event frame, a log line or the debug log. The window only learns that a key is set.
  • The test scans every answer, the event stream, the logs and every file in the data dir for the key and the address.

Bun Inbox only. The Inbox has no Pi twin.

The phone's door has no settings route, so a phone cannot pair or test an agent. It can still write to one and sees the same line.

Tests

  • packages/server/inbox-cloud-wake.test.ts, against a stub webhook on loopback: the request on New message and on a reply, bundling inside the minute, a timeout never resent, 5xx then 429 then started, the key never leaking, and Remove stopping wakes.
  • tests/e2e/inbox-cloud-wake.spec.ts: pair, Send a test, New message, then the Woke line.
  • No real routine was called.

Marks

  • Each kind of cloud agent has its own mark: a Claude Code routine keeps Claude Code's mark, a Grok Bot routine shows Grok Bot's mark, and any other webhook shows a cloud.
  • Grok Bot's mark is the two paths of the "Meet Grok Bot" hero mark on https://x.ai/bot, as served (fetched 2026-11-11), cropped to the circle. It is a black circle with white eyes in every theme, with a thin ring so it holds on dark backgrounds.
  • In the sidebar its eyes glance to a side and back every 8 to 20 s. That motion is ours: the page animates the mark with its own script, which is not copied.

https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv

Settings → Devices → Cloud agents pairs a Claude Code routine, a Grok Bot
routine or any webhook: a name, the address and the key. The agent is then
a live session in New message's To, and a message or reply to it POSTs its
webhook with the key as Bearer (Claude: { text }; Grok Bot and Other: JSON).
At most one wake per thread per minute, held replies bundled; only a 200 is
started; a timeout is never resent; 5xx retries; 429 waits for Retry-After;
a refused key waits for a new one. The thread says "Woke <name> · run
started" with the run link, or why not. The address and key live only in
inbox/cloud-agents.json (0600) and never reach an answer, event or log.

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
Each kind of cloud agent has its own host (cloud-claude, cloud-grok, cloud),
so its mark and name follow as every agent's do: a Claude Code routine
keeps Claude Code's mark and rig, a Grok Bot routine shows Grok Bot's mark
(the x.ai/bot hero mark's paths, eyes as holes), any other webhook the
cloud. In the sidebar the Grok Bot mark is a rig whose eyes glance to a
side and back every 8 to 20 s, paused off screen and still under reduced
motion, as the owner approved.

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
…agents

The shared parts' ib- classes need their rule in the Inbox's own sheet
(inbox-thread-css.test.ts), and with phones off Devices now holds Over your
tailnet and Cloud agents.

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
…theme

A fixed near-black circle and white eyes on the mark and its sidebar rig,
with a thin ring of the text colour at 30% so it holds on dark grounds.

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
…./inbox-cloud

Devices.tsx: main's guest prop on the tailnet block, and the Cloud agents section after it.

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
Main's guard: every name in INBOX_HOST_NAMES is in INBOX_WAKE_AGENT_NAMES.

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
Host names and the wake line's name list: main's OpenClaw, then the cloud hosts.

Claude-Session: https://claude.ai/code/session_01VJ6b1oES3jfkCyDmf8uKzv
@backnotprop
backnotprop marked this pull request as ready for review November 12, 2026 17:29
@backnotprop
backnotprop merged commit fce38c0 into main Nov 12, 2026
67 of 68 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

⌂ 换网址