Skip to content

Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.

docs: network screens and the cloud assistants switch

leepokaieae6fcfa9563
diff --git a/docs/design/codync-network.md b/docs/design/codync-network.md
index 57708203..861587fa 100644
--- a/docs/design/codync-network.md
+++ b/docs/design/codync-network.md
@@ -143,12 +143,15 @@ A VPS can be a member (the host or the standalone daemon, with its own bots or a
The build plan, with what each step touches and when it's done: [what's left](../plans/codync-network-next.md).
-1. Codync-run iroh relays as the default connector.
-2. Re-sign a computer's location when its address changes: today a `private` network without Tailscale loses a
+Done: the network screens and the cloud assistants switch in every client (2.29.0): the desktop app and the
+terminal UI manage the network, phones show it, and a `network` event keeps them current.
+
+1. Per-bot offering and inbound rules (needed before networks shared with other people).
+2. Codync-run iroh relays as the default connector.
+3. Re-sign a computer's location when its address changes: today a `private` network without Tailscale loses a
computer that changes networks until its host restarts.
-3. App switches for cloud assistants and a network screen, in every client.
4. The cloud assistant reaching bots on the connected computer's network.
-5. A local MCP server for agents that aren't Codync bots; per-network lists of offered bots and inbound rules
- (needed before networks shared with other people).
-6. Account networks; several networks per computer.
-7. A control channel for the standalone daemon on Windows (named pipe).
+5. A local MCP server for agents that aren't Codync bots.
+6. Hellos that carry only what changed, lifting the roster's per-computer cap.
+7. Account networks; several networks per computer.
+8. A control channel for the standalone daemon on Windows (named pipe).
diff --git a/docs/features/cloud-assistants.md b/docs/features/cloud-assistants.md
index dae3f832..3b2f9f9a 100644
--- a/docs/features/cloud-assistants.md
+++ b/docs/features/cloud-assistants.md
@@ -37,8 +37,11 @@ ChatGPT / Claude ──MCP over HTTPS──▶ mcp.codync.dev (cloud Worker)
The cloud sees these calls in plain text, and a bot can run anything on its computer, so the computer decides:
-- **Off by default.** `codync-host cloud --assistants on` (local API `setAssistants`, loopback only) turns it on
- for one computer; the setting is the `assistants` field of `cloudStatus`. There's no app switch yet.
+- **Off by default.** The **Cloud assistants** switch on the computer turns it on for that computer: the desktop
+ app (Settings → Computers, beside the account rows, shown while the computer is in the account) and the terminal
+ UI's network sheet (`N`, then `a`), or `codync-host cloud --assistants on`. All go through the local API
+ `setAssistants`, loopback only. The setting is the `assistants` field of `cloudStatus` and of `networkView`, which
+ phones read (they show it in the network sheet and can't change it); the `network` event carries a change.
- **Only the computer's own account.** The Worker routes a call only to computers the token's account owns, and
the host checks the call's account against its owner again.
- **Not on a private relay**: it has no accounts, so the host ignores `assistant.call` there.
@@ -73,7 +76,6 @@ What lifts them, and in what order: [what's left](../plans/codync-network-next.m
| Limit | Why, and what lifts it |
|---|---|
| Hosts before 2.28.0 don't answer (`assistant.call` is ignored, the call times out after 10 s) | the host side ships in 2.28.0 |
-| Only `codync-host cloud --assistants on`; no app switch | an app switch in every client (desktop, iPhone, Android, TUI) is planned |
| Only computers in the account that use the Codync relay; a private relay has no accounts | by design: the account is how the cloud knows whose computer it is |
| Only the connected computer's bots, not bots elsewhere in its codync-network | the assistant isn't a network agent yet ([design](../design/codync-network.md#next-in-order)) |
| No hidden bots or groups | the same visibility rule as `list_bots` for bots |
diff --git a/docs/features/codync-network.md b/docs/features/codync-network.md
index a283450f..921b5cc3 100644
--- a/docs/features/codync-network.md
+++ b/docs/features/codync-network.md
@@ -8,7 +8,9 @@ Why it is built this way, the options weighed and what comes next: [design](../d
## Set it up
-From a terminal on each computer (the API methods are loopback-only: phones can't change who is in):
+On each computer, in the desktop app (Settings → Computers, the **Network** section of each computer it manages,
+`NetworkSection.tsx`), the terminal UI (`N`, `host/src/tui/manage/network.rs`) or the CLI. These are the only
+clients that change membership: the `network*` API methods are loopback-only, like pairing a device.
```sh
codync-host network create [name] [--connector public|private|https://relay] # the first computer: the owner
@@ -18,6 +20,21 @@ codync-host network #
codync-host network peers | promote <computer> | remove <computer> [--cascade] | recover <code>
```
+The apps show the recovery code once, in a sheet that only "I saved it" closes; the host keeps it nowhere and the
+apps never fetch it again. An invite shows when it stops working (`networkInvite` → `expiresAt`). Each computer row
+offers only what this computer may do to it: the host says so per row (`canRemove`, `canPromote`, from
+`Role::removes` and `Role::promotes` in the crate), so the apps never work out the role rules themselves.
+
+The iPhone and Android apps read the network through `networkView` (allowed for paired devices over the encrypted
+channel): the computers with their roles, presence and offered bots, and whether cloud assistants are on. Never an
+invite or the recovery code. The network button on a computer's row in Settings opens it; it's hidden when the host
+is older (unknown method) or the computer is neither in a network nor has cloud assistants on.
+
+**Live**: the node ticks a change hook (`Node::changes`, a `watch` channel) when members, roles, names, presence or
+offered agents change; the host sends a `network` event (`{"type":"network","network": <networkView>}`) to every
+client then and when cloud assistants are switched. `networkView` also asks the other computers in the background
+when what it heard is over a minute old, so opening the screen brings presence up to date through that event.
+
`create` prints the **recovery code** once: the network's root key, kept on no computer. The connector picks the
fallback when two computers can't connect directly: iroh's public relays (`public`, the default), the user's own
`iroh-relay` (a URL), or none (`private`: same network, Tailscale or a VPN). A computer's name defaults to its host
@@ -67,6 +84,8 @@ that was off learns of a removal.
from a bot the computer no longer offers (renamed or deleted while it worked).
- Exchange notices carry `botMessage.peerName` ("Reviewer on desk") for the bot on the other computer, whose id
isn't in this computer's bot list; every client shows that name in the row, the pair sheet and its author labels.
+- Other computers' bots stay out of the apps' bot lists: a phone chats with a computer's own bots, and a bot
+ elsewhere is reached by asking a local one. The network screens list them under their computer.
- A letter to a computer that is away waits in the sender's outbox for up to a day, and so does one for a computer
that has started but not offered its bots yet (it answers *later*; offering them calls everyone back). A reply
reaches its request even when the asking bot was renamed or hidden meanwhile. The chain's hop limit counts
@@ -82,7 +101,6 @@ that was off learns of a removal.
Planned in order, with what each step touches: [what's left](../plans/codync-network-next.md).
-- The apps have no network screen: setup is the CLI above.
- One network per computer; the `.network` address suffix comes with several.
- Shared networks (other people's computers) need the per-network list of offered bots and inbound rules first.
- Bots can't reach Claude Code or Codex sessions on another computer through the host (the standalone daemon can).
@@ -96,8 +114,13 @@ Planned in order, with what each step touches: [what's left](../plans/codync-net
- `host/crates/network`: the crate (`node/`, `roster.rs`, `guard.rs`, `reach.rs`, `wire.rs`); `cargo test -p codync-network`
runs computers on one machine over direct connections, without a relay or internet.
-- `host/src/network/`: the host's node, published bots and address names, the `network*` API methods.
+- `host/src/network/`: the host's node, published bots and address names, the `network*` API methods, `networkView`
+ and the `network` event.
+- Clients: desktop `apps/desktop/src/renderer/views/settings/NetworkSection.tsx` (+ `NetworkSheets.tsx`,
+ `store/network.ts`), terminal `host/src/tui/manage/network.rs` + `view/network.rs`, iPhone
+ `apps/ios/Kit/Sources/CodyncUI/NetworkSheet.swift`, Android `apps/android/app/.../NetworkSheet.kt`.
- `host/src/chat/team/remote.rs`, `directory.rs`: requests and replies across computers, `list_bots`.
- `host/src/network_cli.rs`: `codync-host network`.
- `host/tests/network_e2e.rs`: two real hosts in one network, a bot messaging a bot on the other computer through
- approval and back, and a request its recipient's user stops and one that fails.
+ approval and back, a request its recipient's user stops and one that fails, and the view with its per-row
+ permissions and the `network` event reaching both computers' apps on a promotion.
diff --git a/docs/plans/codync-network-next.md b/docs/plans/codync-network-next.md
index 83c95fd0..87cd19d9 100644
--- a/docs/plans/codync-network-next.md
+++ b/docs/plans/codync-network-next.md
@@ -1,6 +1,7 @@
# codync-network and cloud assistants: what's left
-Status (2026-10-26): planned, nothing below is built. 2.28.0 shipped the network (`host/crates/network`, crate
+Status (2026-10-26): package 1 (network screens, cloud assistants switch) is built for 2.29.0; the rest is
+planned. 2.28.0 shipped the network (`host/crates/network`, crate
`codync-network` 0.1.1 on crates.io) and the cloud assistant connector (`mcp.codync.dev`). Read first:
[design](../design/codync-network.md) (why, and the decisions already made), [feature](../features/codync-network.md)
(how it behaves today), [cloud assistants](../features/cloud-assistants.md), [relay §7.9](../reference/remote-relay.md).
@@ -39,7 +40,11 @@ The work is split into packages, in the order to build them. Each one ships on i
on one Mac work for the network ([the earlier e2e](../features/codync-network.md#code-and-verification)).
- Never name another product a feature copies, in code, docs or commits.
-## 1. Network screens in the apps
+## 1. Network screens in the apps (built, 2.29.0)
+
+Built as below, with these choices: no QR on the invite (nothing scans one: joining happens on a computer, by
+paste); other computers' bots stay out of the bot list (the recommended default); the desktop's remove dialog offers
+"Remove" and "Remove with its invites" instead of a toggle. What it does now: [feature](../features/codync-network.md#set-it-up).
**Goal**: everything `codync-host network` does, done from the desktop app and the terminal; phones see the
network without changing it.
diff --git a/docs/reference/analytics-events.md b/docs/reference/analytics-events.md
index 8c773f84..65a5a8b9 100644
--- a/docs/reference/analytics-events.md
+++ b/docs/reference/analytics-events.md
@@ -99,6 +99,7 @@ host answers and sends it once the host is up.
| `setting_changed` | host, iOS, Android | A setting is switched | `setting` (host: `remote_access`/`remote_access_url` (`on`: a relay address is saved, never the address)/`approval` (`on`: approved without the code)/`automatic_updates`/`remote_screen`/`cloud_assistants`; phones: `push`/`live_activities`), `on` |
| `host_update_installed` | host | `installHostUpdate` | — |
| `network_joined` | host | `networkCreate` / `networkJoin`: the computer is in a network of the user's computers | `via` (`create`/`invite`), never a name, invite or connector address |
+| `network_changed` | host | `networkInvite` / `networkPromote` / `networkRemove` / `networkRecover` | `action` (`invite`/`promote`/`remove`/`recover`), never a computer's name, the invite or the recovery code |
## Screens
@@ -125,6 +126,7 @@ host answers and sends it once the host is up.
| `help` | — | — | keys overlay |
| `library` | a chat's Library (iPhone: the details tab; Android: its sheet) | library tab | library overlay |
| `artifact` | an artifact's viewer | an artifact's viewer | — (opens in the browser) |
+| `network` | network sheet (a computer's row in Settings) | — (part of `computers`) | network sheet |
## Funnels
diff --git a/docs/reference/remote-relay.md b/docs/reference/remote-relay.md
index ce6df0fa..44aba76a 100644
--- a/docs/reference/remote-relay.md
+++ b/docs/reference/remote-relay.md
@@ -467,7 +467,7 @@ Close code 總表:`1000` 正常、`1011` 內部錯誤/逾時、`4001 unautho
- **登入**:Clerk 是 authorization server,Worker 只是 protected resource。未帶有效 token → `401`,`WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp", scope="profile email"`;metadata 指向 Clerk issuer(`/.well-known/oauth-authorization-server` 也代轉 Clerk 的,給舊 client)。Client 以 CIMD 註冊(DCR 關閉)。Token 必須是 Clerk 發的 OAuth access token(`at+jwt`,或 opaque 時向 Clerk 驗),`aud` 必須等於 `<origin>/mcp`;App 的 session token 不算。`ASSISTANT_LIMITER`:每帳號每分鐘 120 次。
- **路由**:Worker 只把呼叫送到 token 帳號擁有、`active` 的 computer。`list_computers` 由 Worker 從 D1 回答;其餘工具:指定 `computer`(名稱或 id)→ 該台;未指定時帳號只有一台、或只有一台在線 → 該台;`list_bots`/`read_replies` 在多台在線時每台都問並合併成 `{computers:[{computer, …}]}`;`message_bot` 則要求指定。
- **DO**:`POST /internal/assistant {user, tool, args}` → host 不在線 `503 {"ok":false,"code":"offline"}`;否則送 `assistant.call`,在 request 存活期間等同 `id` 的 `assistant.result`,最多 10 秒(逾時 `{"ok":false,"code":"timeout"}`,舊 host 會忽略這個訊息)。host 斷線時等待中的呼叫一律 `offline`。只在 request 存活時佔用 DO,不排隊、不存任何內容。
-- **Host**(`chat::team::assistant`):預設關閉,`setAssistants`(loopback only,`codync-host cloud --assistants on|off`)才開;`user` 必須等於 host 的 owner(`/v1/host/state`);private relay 上不處理。`message_bot` 走一般 bot request(`Back::Assistant`),回覆留在 host 記憶體給 `read_replies`(最新 50 則,同時最多 16 則執行中,重啟即忘)。
+- **Host**(`chat::team::assistant`):預設關閉,`setAssistants`(loopback only:桌面 app 與 TUI 的 Cloud assistants 開關,或 `codync-host cloud --assistants on|off`)才開;`user` 必須等於 host 的 owner(`/v1/host/state`);private relay 上不處理。`message_bot` 走一般 bot request(`Back::Assistant`),回覆留在 host 記憶體給 `read_replies`(最新 50 則,同時最多 16 則執行中,重啟即忘)。
- **信任邊界**:和 §7.8 一樣,雲端以 HTTPS 解開並看得到這些呼叫與回覆的明文,不是 §6 的端對端加密。因此要電腦本機同意(開關)才放行,雲端無法自行替電腦打開;App 與文件都需明講。
---
diff --git a/host/crates/network/README.md b/host/crates/network/README.md
index 93e94b4a..6a2a3346 100644
--- a/host/crates/network/README.md
+++ b/host/crates/network/README.md
@@ -140,6 +140,9 @@ while let Some(message) = inbox.recv().await {
}
```
+`node.changes()` ticks whenever `node.directory()` would show something new (a computer joins or leaves, a role,
+name or presence changes, another computer offers different agents), for an app that shows the network live.
+
## Build
```sh
diff --git a/host/tests/e2e.rs b/host/tests/e2e.rs
index 7b05f7fc..c785ddd5 100644
--- a/host/tests/e2e.rs
+++ b/host/tests/e2e.rs
@@ -507,6 +507,9 @@ async fn catch_up(host: &Host) -> Vec<Value> {
let line: String = buf.drain(..=i).collect();
if let Some(data) = line.trim_end().strip_prefix("data:")
&& let Ok(v) = serde_json::from_str::<Value>(data.trim_start())
+ // A live usage refresh lands whenever the agents' usage poll finishes (later on a
+ // busy machine); its shape is `hello.usage`'s.
+ && v["type"] != "usage"
{
events.push(v);
}
diff --git a/web/content/docs/cloud-assistants.mdx b/web/content/docs/cloud-assistants.mdx
index 8aeebbe4..cb58e3fb 100644
--- a/web/content/docs/cloud-assistants.mdx
+++ b/web/content/docs/cloud-assistants.mdx
@@ -2,19 +2,13 @@ You can give a task to your Codync bots from an assistant you already use on the
## Turn it on for a computer
-Cloud assistants are off on every computer until you turn them on there. On the computer whose bots the assistant may use, run:
+Cloud assistants are off on every computer until you turn them on there, at the computer whose bots the assistant may use:
-```sh
-codync-host cloud --assistants on
-```
-
-On a Mac where you installed the app from the disk image rather than with Homebrew, `codync-host` is inside the app:
-
-```sh
-/Applications/Codync.app/Contents/Resources/codync-host cloud --assistants on
-```
+- **Desktop:** Settings → **Computers**, the **Cloud assistants** switch under the computer's account rows.
+- **Terminal UI:** `N` opens the network sheet; `a` switches **Cloud assistants**.
+- **Command line:** `codync-host cloud --assistants on` (`off` turns it off; `codync-host cloud` shows it as `assistants: on`). On a Mac where you installed the app from the disk image rather than with Homebrew, `codync-host` is inside the app: `/Applications/Codync.app/Contents/Resources/codync-host`.
-The computer has to be in your Codync account (signed in) and use the Codync relay. `codync-host cloud` shows the setting as `assistants: on`; `--assistants off` turns it off again.
+The switch carries the same warning as [Privacy](#privacy) below: Codync's cloud can read these calls. Phones show whether it's on (the network button on a computer's row in **Settings**) but can't change it. The computer has to be in your Codync account (signed in) and use the Codync relay.
## Add the connector
@@ -40,7 +34,7 @@ In the bot's chat, the request shows as a row saying **Message from Cloud assist
## Current limits
- **The computer needs Codync 2.28.0 or later.** An older one doesn't answer the assistant.
-- **Turned on from a terminal only.** The apps have no switch for cloud assistants yet.
+- **Turned on at the computer.** The desktop app, the terminal UI or `codync-host` changes it; phones only show it.
- **Only computers in your Codync account that use the Codync relay.** A computer that uses your own relay can't be reached, and neither can a computer that is only in your [network of computers](/docs/teamwork#bots-on-your-other-computers) and not in your account: the assistant reaches the bots of the computer it talks to, not that computer's network.
- **No hidden bots or group chats.** The assistant sees the same bots another bot can message.
- **It can't be told when a reply is ready.** A hosted assistant only acts when you write to it, so ask it to check on the task later.
diff --git a/web/content/docs/teamwork.mdx b/web/content/docs/teamwork.mdx
index c91b6bc3..571a60dc 100644
--- a/web/content/docs/teamwork.mdx
+++ b/web/content/docs/teamwork.mdx
@@ -54,32 +54,25 @@ In a [group chat](/docs/groups), members don't message each other this way; they
## Bots on your other computers
-Your computers can join one private network, codync-network, so a bot on your desktop can ask a bot on your laptop or server. Computers connect to each other directly; when they can't, traffic goes through a relay that sees only encrypted data. The network stays off until you set it up, from a terminal on each computer.
+Your computers can join one private network, codync-network, so a bot on your desktop can ask a bot on your laptop or server. Computers connect to each other directly; when they can't, traffic goes through a relay that sees only encrypted data. The network stays off until you set it up on each computer, in the Codync app or the terminal UI there. Phones only show it: who is in the network is decided at a computer.
-On the first computer, create the network. That computer becomes its owner:
+- **Desktop:** Settings → **Computers**, the **Network** section under each computer.
+- **Terminal UI:** `N` (or **Network** in the `^k` palette).
+- **iPhone and Android:** the network button on a computer's row in **Settings** lists the computers, whether each one answers and the bots it offers.
-```sh
-codync-host network create desk
-```
+On the first computer, choose **Create network**. That computer becomes its owner. Codync then shows a **recovery code**, once: keep it in a password manager. It makes another computer the owner if this one is lost (**Recover ownership** on that computer), and it's kept on no computer, so it can't be shown again.
-On a Mac where you installed the app from the disk image rather than with Homebrew, `codync-host` is inside the app: run `/Applications/Codync.app/Contents/Resources/codync-host network …` instead, here and below.
+Then add each other computer with a one-time invite, good for an hour while the inviting computer stays on: **Invite a computer** on the owner, then **Join with invite** on the new computer and paste it.
-It prints a **recovery code** once. Keep it in a password manager: it makes another computer the owner if this one is lost (`codync-host network recover <code>`).
+The network lists every computer with its role, whether it answers and how many bots it offers. The owner can make a computer an admin (**Make admin**), which can then invite computers and remove plain members too. **Remove** takes a computer out for good; **Remove with its invites** is for a stolen one, to also remove every computer it added. A computer that was off hears about a removal when it's back.
-Then add each other computer with a one-time invite, good for an hour while the inviting computer stays on:
-
-```sh
-codync-host network invite # on the owner
-codync-host network join '<invite>' laptop # on the new computer
-```
-
-`codync-host network` shows the computers, their roles and their bots. The owner can make a computer an admin (`codync-host network promote laptop`), which can then invite and remove computers too. `codync-host network remove laptop` takes a computer out for good; add `--cascade` for a stolen one, to also remove every computer it added. A computer that was off hears about a removal when it's back.
+Prefer the command line? `codync-host network` does the same: `create [name]`, `invite`, `join '<invite>' [name]`, `peers`, `promote <computer>`, `remove <computer> [--cascade]` and `recover <code>`. On a Mac where you installed the app from the disk image rather than with Homebrew, `codync-host` is inside the app: `/Applications/Codync.app/Contents/Resources/codync-host`.
Once your computers are in the network, nothing else changes for your bots. A bot lists the bots on your other computers along with its own, as `name@computer` (for example `reviewer@desk`), and asks them the same way. The request runs in that bot's chat on its computer, with that computer's approvals, and the answer comes back to the sender. The rows in the chats name the bot and its computer, for example "Messaged Reviewer on desk".
- **Away computers:** a request to a computer that's asleep waits up to a day and goes out when it's back.
- **Limits:** besides the limits below, each computer accepts a burst of 5 messages between the same two bots, then one every 2 minutes, and refuses the same words twice within 10 minutes.
-- **Connector:** by default computers that can't connect directly use iroh's public relays, meant for trying things out. Add `--connector https://your-relay` to `create` or `join` to use your own `iroh-relay`, or `--connector private` for no relay at all (computers on the same network, Tailscale or a VPN).
+- **Connector:** when you create or join, **When there's no direct path** picks how computers reach each other: **Public relays** (iroh's, meant for trying things out; the default), **Your own relay** (an `iroh-relay` you run) or **Private: direct only** (computers on the same network, Tailscale or a VPN). On the command line: `--connector public|private|https://your-relay`.
## Manage the team