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.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
docs: plan what's left for codync-network and cloud assistants
leepokaic9471e2a8b16
diff --git a/docs/README.md b/docs/README.mdindex b6174de7..61300948 100644--- a/docs/README.md+++ b/docs/README.md@@ -57,6 +57,7 @@ Source review, a passing build, local integration tests and production acceptanc## Plans- [Android parity and acceptance](plans/android-app.md)+- [codync-network and cloud assistants: what's left](plans/codync-network-next.md) (network screens in every app, access rules, Codync's own relays, and the rest, in build order)- [Harness memory](plans/harness-memory.md) (the switch that keeps a harness's own memory on; a choice of it instead of Codync's, planned)- [Error tracking detail](plans/error-tracking-detail.md) (symbolicated iPhone crashes and sessions, built; consented problem reports, proposed)diff --git a/docs/design/codync-network.md b/docs/design/codync-network.mdindex 143bdf28..57708203 100644--- a/docs/design/codync-network.md+++ b/docs/design/codync-network.md@@ -141,6 +141,8 @@ A VPS can be a member (the host or the standalone daemon, with its own bots or a## Next, in order+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 acomputer that changes networks until its host restarts.diff --git a/docs/features/cloud-assistants.md b/docs/features/cloud-assistants.mdindex ab22ec9e..dae3f832 100644--- a/docs/features/cloud-assistants.md+++ b/docs/features/cloud-assistants.md@@ -68,6 +68,8 @@ pass on both instances. A local check of a deployment:## Current limits+What lifts them, and in what order: [what's left](../plans/codync-network-next.md).+| 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 |diff --git a/docs/features/codync-network.md b/docs/features/codync-network.mdindex d914da59..a283450f 100644--- a/docs/features/codync-network.md+++ b/docs/features/codync-network.md@@ -80,6 +80,8 @@ that was off learns of a removal.## Not yet+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.diff --git a/docs/plans/codync-network-next.md b/docs/plans/codync-network-next.mdnew file mode 100644index 00000000..83c95fd0--- /dev/null+++ b/docs/plans/codync-network-next.md@@ -0,0 +1,208 @@+# 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+`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).++Today every network and assistant setting is a command on the computer (`codync-host network …`,+`codync-host cloud --assistants on|off`). The apps only show the result: an exchange with a bot on another+computer reads "Messaged Reviewer on laptop". And there are no access rules: any agent on any member computer can+message any visible bot on any other.++The work is split into packages, in the order to build them. Each one ships on its own.++## Rules for whoever builds this++- **Host owns the logic** ([overview](../architecture/overview.md#host-owns-the-logic)). Rules, checks and state live+ in the host or the crate, and clients only show them and send intents. A client that needs data gets a new host+ method.+- **Every client in the same change** (CLAUDE.md, cross-platform UI): iPhone (`apps/ios/`), Android (`apps/android/`),+ desktop (`apps/desktop/`, one codebase for macOS, Linux and Windows) and the terminal UI (`host/src/tui/`). Name+ every client a package leaves out, and why, in the PR.+- **Membership is decided at a computer.** The `network*` host methods and `setAssistants` are loopback-only+ (`host/src/api/devices.rs`, `LOCAL_ONLY`), the same rule as pairing a device. The cloud never admits. Keep that:+ only the desktop app and the terminal (both on the computer) change membership. Phones get read-only views.+- **Compatibility**: new fields and methods are additive. An app that calls a method an older host lacks gets+ "unknown method", so it hides that section and doesn't show an error. No `minApp` change unless something is+ renamed or removed ([compatibility](../reference/compatibility.md)).+- **The crate**: a change to `host/crates/network` raises its 0.x version (minor for API additions) once per release.+ `network-crate.yml` checks that, then mirrors the crate to `leepokai/codync-network` and publishes it. Merge+ `dev → main` with a merge commit, never a squash: the mirror only fast-forwards+ ([crate releases](../guides/development.md#crate-releases)).+- **Release**: a minor bump of the app version (feature). Write the iPhone and Android WhatsNew sections when a phone+ app changes.+- **Docs** in the same change: the feature doc, the design doc's "Next" list, the user manual (`teamwork.mdx`+ "Bots on your other computers", `cloud-assistants.mdx`), and privacy if what the cloud or relay sees changes.+- **Process**: one worktree per package (`feat/network-ui`, …), the `after-change` workflow, minimal e2e on the Mac+ (the desktop app through `npm run dev`, the iPhone simulator, the Android emulator, the terminal in tmux). Two hosts+ 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++**Goal**: everything `codync-host network` does, done from the desktop app and the terminal; phones see the+network without changing it.++### Host++- `networkStatus` and `networkPeers` already return what the screens need: this computer's name and role, the+ connector, and the other computers with role, online, and the bots they offer (`host/src/api/network.rs`).+ Check each field against the UI below and add what's missing. Keep the JSON additive.+- **Live updates**: emit a `network` event (`hub.events`, like `cloud`) when membership, roles, names or presence+ change, so clients refresh without polling. The node learns of changes on hellos and merges+ (`host/crates/network/src/node/`). Add a change hook to `Node` (a `watch` channel, or a callback set by the host).+ That's a crate API addition.+- **Read-only for phones**: a new method `networkView` (status plus peers, no invite and no recovery). Leave it off+ `LOCAL_ONLY` so paired devices can call it over the encrypted channel. Don't open the existing methods: `networkInvite`+ must stay local.+- The recovery code exists only in `networkCreate`'s answer. The UI must show it once, make the user confirm they+ saved it, and never fetch it again: the host doesn't keep it.++### Desktop (`apps/desktop/src/renderer/views/settings/ComputersView.tsx`, store in `store/`)++A "Network" section on the computer's settings page, styled like the cloud and approval rows already there:++- **Not in a network**: two actions, Create (a computer name defaulting to the host name, plus the connector:+ public, private or a relay URL) and Join (paste an invite, name).+- **Create** shows the recovery code once in a dialog: copy button, a "I saved it" confirmation, and the warning+ that it moves ownership if this computer is lost.+- **Invite**: a one-time code with a QR and its one-hour expiry, copyable.+- **Computers**: one row per computer with name, role badge, online dot and how many bots it offers. Actions by+ role: the owner can promote (admin) and remove; an admin can remove members. Remove confirms in a dialog, with the+ cascade option explained ("also removes the computers it invited; for a stolen computer").+- **Recover**: enter a recovery code to become the owner.+- Calls go through `window.codync`, using the host's loopback API like `setApproval` does+ (`store/cloud.ts`, `ComputersView.tsx`). There are no static inline styles ([desktop styles](../guides/desktop-styles.md)).++### Terminal (`host/src/tui/`, overlays in `view/`, keys in `app/overlay_keys.rs`)++The same as the desktop, as an overlay reached from the computer view, keyboard-driven, with confirmations as in+`view/computer_access.rs`. The terminal runs on the computer, so it gets the full set.++### iPhone and Android (read-only)++- In each computer's settings (iPhone `apps/ios/Views/SettingsView.swift` and the computer rows; Android+ `SettingsView.kt`): a "Network" row. It opens a list of the computers in the network, with name, role, online+ and offered bots, plus a note that changes are made on a computer. It's hidden when the host is too old+ (`networkView` unknown) or the computer isn't in a network.+- iOS menus and sheets stay native (`.codyncSheet`, `DropdownMenu`). Android uses the `design` module only.++### The bot list (decide with the user before building)++Recommended default: **don't** mix other computers' bots into the bot list. A phone chats with a computer's own+bots, and a remote bot is reached by asking a local one. Show them in the network screen under their computer+instead. If the user wants them in the list, that is a separate change.++### Cloud assistants switch++Next to "Reach from anywhere" in the desktop and terminal: "Cloud assistants" (`setAssistants`). It carries the+same warning as the manual: the relay can read these calls. Phones show it read-only (it's in `cloudStatus` as+`assistants`; phones need it through `networkView`, or a field next to it). The manual's Cloud assistants page then+describes the switch, not only the command.++### Done when++The desktop app and the terminal can create, invite, join, list, promote, remove and recover on two real hosts.+Phones list the computers. The live event updates every client. Analytics: `setting_changed` for the assistants+switch is already there, and `network_joined` exists; add events for the screens the way+`docs/features/analytics.md` describes.++## 2. Access rules (ACL)++**Goal**: choose which bots each computer offers, and which agents may message them, before a network is ever+shared with other people.++### Model (recommended)++Enforced by the **receiving** computer, like the message budgets: no rule depends on the sender's goodwill, and+nothing new crosses the wire beyond a refusal reason.++1. **Offered to the network**, per bot: a switch, on by default so nothing changes for current users. A bot that's+ off isn't published to the network (`network::publish` filters it), so other computers don't list it, and+ letters to it are refused like letters to an unknown agent. Store it on the bot (`BotConfig`, additive field),+ editable wherever bot settings are: it narrows or widens exposure within the user's own network.+2. **Inbound rules**, per computer: an ordered list of `{from_computer, from_agent, to_bot, allow|deny}` with `*`+ wildcards. The first match wins, and with no rules everything is allowed (today's behavior). Put the check in the+ crate (`Node::set_rules`, checked in `node/inbound.rs` `take()` before handing over), so the standalone daemon+ gets it too (a `rules.json` beside `agents.json`, plus CLI commands). The host stores its rules in kv and pushes+ them to the node. Refuse with a clear reason, for example "laptop doesn't take messages from server's agents".+ The sender's `message_bot` returns it as the tool error. Replies (`reply_to` an outstanding request) always pass,+ or a rule added mid-request would strand it.+3. **Cloud assistant scope**: per bot, "Reachable by cloud assistants", on by default, checked in+ `chat/team/assistant.rs` for `list_bots` and `message_bot`.++The master switches stay loopback-only: being in a network and assistants on or off. The per-bot switches and the+rules are bot or computer settings. Editing rules is local-only (desktop and terminal), like membership. Per-bot+switches may be changed from any paired device.++### Clients++The per-bot switches go in bot settings on every client (iPhone `BotDetailsView`/`BotEditorView`, Android+`BotDetailsView.kt`/`BotSettingsForm.kt`, desktop bot details, terminal bot settings). The rules editor goes in the+desktop and terminal network screen; phones show the rules read-only.++### Tests++Crate: rules match, first match wins, wildcards, replies pass, the daemon's rules file. Host: an unoffered bot isn't+published and its letters are refused, and the assistant scope applies. e2e: two hosts, a deny rule, and a refused+`message_bot` that shows the reason in the sender's chat.++## 3. Codync's own relays as the default connector++Users never run a relay. Codync runs `iroh-relay` on two small VPSs (North America and Europe, ACME TLS), and the+default connector points at them instead of n0's public relays, which are rate-limited and not for production. Keep+`public` (n0) for development, and keep the URL and `private` connectors. Operations: hosting, DNS+(`relay-na.codync.dev`, …), monitoring, and keeping `iroh-relay` in step with the crate's iroh version. Code: the+default connector, the privacy policy's third-party list, and the design doc's relay table. Ask the user before+renting servers.++## 4. A computer's address after it moves++A computer signs where it is into the roster only when the host starts (`refresh_my_addr`). With the `private`+connector and no Tailscale, a laptop that changes networks can't be found until its host restarts. Watch the+endpoint's addresses (iroh exposes changes), re-sign `Locate` when they change, and hello everyone. The roster keeps+only each computer's newest location, so this doesn't grow the log. Test: change addresses in a two-node test.++## 5. Cloud assistants beyond the connected computer++The connector reaches only the bots of the computer it talks to. To reach that computer's network: publish the+assistant as an agent of that computer (or let the host send letters for it under a reserved name), route+`message_bot` to `name@computer` through `chat::team::remote`, and keep replies in the assistant's reply store. Mind+the ACL from package 2: the assistant is a sender like any other.++## 6. A local MCP server for agents that aren't Codync bots++Claude Code or Codex sessions on the same computer use the standalone daemon's CLI today. Give them an MCP server:+`codync-host mcp network` over stdio, or the daemon's own. It offers `list_bots`, `message_bot` and `read_replies`,+backed by the host, with the session registered as an agent. It's a local alternative to the cloud connector and+needs no cloud.++## 7. Lifting the roster's per-computer cap++Each computer may have at most 256 roster entries, the oldest kept. An owner or admin that has made 256 admissions,+promotions and removals can make no more (documented in the feature doc's "Not yet"). Fix: hellos that carry the+changes since the last exchange (a version vector or a hash per signer) instead of the whole log. Then compaction+can drop entries that no longer count (an admission whose computer was removed, for example) without the 1 MiB+frame as the reason. This is a wire change: keep old peers working by falling back to the whole log.++## 8. Account networks and several networks per computer++- **Account networks**: the account vouches for its computers, so a computer signed into the account is admitted+ without an invite. It's still signed by a member computer, never by the cloud.+- **Several networks per computer**: addresses get a network suffix (`[email protected]`), bare names resolve+ within the default network, and names that collide across networks stay apart. The crate takes several rosters,+ and the host stores one per network.++## 9. Windows++The standalone daemon's control socket and the Claude Code inbox are Unix sockets today. On Windows, add a named+pipe for the control door, and Claude Code's named pipe with its token (`reach.rs`, `bin/codync-network/control.rs`).+Then run the crate's tests on Windows in its mirror CI (`host/crates/network/.github/workflows/ci.yml` skips them).++## 10. A connector users host themselves (decide first)++Today the only self-hosted path is running the whole `cloud/` Worker with one's own Clerk and pointing the host at+it with `CODYNC_CLOUD_URL`. A lighter path, the host serving MCP itself behind the user's own HTTPS, needs its own+OAuth server, because ChatGPT and Claude require OAuth for remote connectors. The user is still deciding whether to+offer this. Until then, document the full-cloud path in `cloud/README.md` if anyone asks.