diverge-daemons · diff
git:20261116.c980f6b to git:20261117.db414c5
1 added, 1 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: diverge-daemons
description: Connecting a Diverge daemon to providers and to other daemons. Covers provider records (`diverge run providers add|get|list|edit|delete|enable|disable|tag|untag`, incoming vs outgoing direction, ips and address, the per-provider `announcement`, `accept_daemons` and `messageable` settings, what an edit does to a live connection, status, capabilities and capacity), the peers seen through providers (`diverge run providers daemons list|listen|message`, direct messages), remote daemon records (`diverge run daemons add|get|list|edit|delete|tag|untag`, DaemonId, routes by providers / ips / addresses), the `relay` member every request may carry to have another daemon serve it, and connected standalone tools (`diverge run connected-standalone-tools create|get|list|edit|delete|tag|untag|attach-agent-instance|attach-agent-template|detach-agent-instance|detach-agent-template`), which hold another daemon's tool here for this daemon's agents. Load it when a provider shows `disconnected`, when adding or changing a provider, when making two daemons talk, when a request should run on another daemon, or when an agent needs a tool that lives on another daemon.
---
# Diverge daemons: providers, peers, relay, connected tools
A **provider** is where containers run and volumes live; a daemon works with the providers it has records
of. A provider is also the meeting point between daemons: two daemons connected to the same provider can
reach each other through it. A daemon keeps **remote daemon records** (one account of ours on another
daemon), may serve any request **on** such a remote (`relay`), and may hold a tool that runs on a remote
under a local name for its own agents (a **connected standalone tool**).
All commands are `diverge run <family> <request> '<JSON body>'`, one compact JSON line per answer. Run
`<command> request-schema` / `response-schema` for exact shapes. An identity is always
`{"issuer":"…","subject":"…"}`. Grants named below are explained in `diverge-access`.
**What has never been run live:** everything daemon-to-daemon. Remote daemon records connecting, `relay`,
connected standalone tools, and direct messages (`providers daemons listen|message`) are built and
compile-checked only. Provider records with an outgoing provider are live-proven. Expect to debug the
two-daemon flow; see "Not verified" at the end.
## 1. Provider records (`diverge run providers …`)
One record per provider identity. The record says which end dials, whether the daemon works with it
(`enabled`), and three independent things the daemon does **on that provider** while connected:
| Field | Default | What it does |
|---|---|---|
| `announcement` | absent | One line of text. Present: the daemon **announces itself** on that provider with it, so other parties connected there see it in `providers daemons list`. Absent: the daemon is not listed there. |
| `accept_daemons` | `true` | Whether the daemon **accepts connections from other daemons** through that provider (relay into it, connected tools from it). |
| `messageable` | `false` | Whether the daemon **listens for direct messages** on that provider. |
The three are independent: any combination is valid, and none is needed for the daemon to use the provider
for containers, volumes and images, or to **send** a direct message through it.
### Add
```bash
# Outgoing: the daemon dials the provider. Dialled at once when enabled.
diverge run providers add '{"identity":{"issuer":"https://identity.diverge.network","subject":"github.12345.provider"},
"direction":"outgoing","address":"127.0.0.1:14979",
"announcement":"daemon A, build farm east","accept_daemons":true,"messageable":true,
"description":"local podman provider","tags":["local"]}'
# Incoming: the provider dials the daemon; admitted only from these source IPs (absent = any, [] = none).
diverge run providers add '{"identity":{"issuer":"https://issuer.example","subject":"edge-provider"},
"direction":"incoming","ips":[{"type":"cidr","cidr":"10.0.0.0/24"},{"type":"ip","ip":"203.0.113.7"}]}'
# -> "added" | "exists" | "forbidden" | {"error":…}
```
Members: `identity` (required), `direction` with its own members beside it (`address` for `outgoing`: a
`host:port` dialled as `ws://host:port/`, or a full URL; `ips` for `incoming`), `announcement` (default
absent: not announced), `accept_daemons` (default `true`), `messageable` (default `false`), `enabled`
(default `true`), `description` (your own note about the provider; the provider never sees it), `tags`.
Grant: `{"providers":["add"]}`.
An `announcement` is one line of plain text, 1 to 132 characters, no control characters, no leading or
trailing whitespace. It is per provider: the same daemon may announce itself differently on each.
Rules:
- Exactly one direction per provider. An incoming provider is never dialled; an outgoing provider that
dials in is refused. An IP is never a dial target, and an address is never an IP filter.
- Every connection is encrypted after its handshake, with keys only its two ends hold. That includes a
daemon-to-daemon connection relayed through a provider: the provider carries it and cannot read it. The
provider still sees which daemons talk, when, and how much.
- The mutual handshake establishes the provider's identity; an outgoing dial is refused unless the
identity that answers is the record's.
- The other side must agree: the provider's own `provider.yaml` must accept this daemon's identity (and,
for an incoming provider, dial this daemon), and each must have its own `identity` in its document, signed in
under its root. The two need not be at the same issuer. See `diverge-config`.
- The daemon holds at most one connection per provider identity.
### Read: status, capabilities, capacity
```bash
diverge run providers list # {"added":{…}} per provider, then "listed"
diverge run providers list '{"connected":true,"enabled":true}'
diverge run providers get '{"identity":{"issuer":"https://identity.diverge.network","subject":"github.12345.provider"}}' # {"found":{…}}
diverge run providers list --jq '.added? | {subject: .identity.subject, status: .status.type, enabled, announcement, accept_daemons, messageable}'
```
A provider item: `identity`, `direction` (+ `address` or `ips`), `announcement` (absent when the daemon
does not announce itself there), `accept_daemons`, `messageable`, `enabled`, `description`, `tags`,
`created`, `creator`, `status`, `capacity`.
- `status.type` is `disconnected`, `connected` (with `info`), or `different_version` (with `info`).
`info` is what the provider answered: `version` and `capabilities`. A provider counts as `connected`
only once that answer is cached. **`different_version`** means the socket is held but the provider is
used for nothing (no container, volume, image, or daemon reached through it) until daemon and provider
are the same version.
- `capabilities` says which optional parts the provider serves: `containers`, `images` (an object:
`store`, there when it keeps a Store, with `build` saying whether it builds; and `registries`, the
registries it pulls from), `volumes_persistent` / `volumes_ephemeral` /
- `volumes_read_only` (each an object of `mount`, `fuse_serve`, `mount_many`, `fuse_serve_many`,
+ `volumes_read_only` (each an object of `create`, `mount`, `fuse_serve`, `mount_many`, `fuse_serve_many`,
`mount_and_fuse_serve`), and `messages` (present only when the provider relays direct messages). A member
absent is the capability absent. The daemon asks a provider nothing its capabilities exclude.
- `capacity` is the provider's latest answer, polled every ten seconds (fixed; not configurable):
`volumes_disk`, `images_disk`, `container_memory`, `container_disk`, in bytes. Absent unless
`connected`.
- List filter members: `identities`, `connected`, `enabled`, plus `count`. `providers list --watch` keeps
the list open: a status or capacity change arrives as `{"changed":{…}}`.
If a record stays `disconnected`: the provider is down or unreachable at `address`; the daemon's identity
is not in the provider's `incoming`; the daemon or the provider has no `identity` in its document, or it is not signed in; or the record is disabled.
The daemon keeps redialling an enabled outgoing provider, so fix the cause and list again.
### Change
```bash
# Edit: every member given replaces the record's; absent members stay.
diverge run providers edit '{"identity":{"issuer":"…","subject":"github.12345.provider"},"description":"main provider"}'
# Announce with a new text, stop accepting other daemons, start hearing messages: one body, nothing closes.
diverge run providers edit '{"identity":{"issuer":"…","subject":"github.12345.provider"},
"announcement":"daemon A, staging","accept_daemons":false,"messageable":true}'
# Stop announcing (null clears; leaving the member out would leave it as it is).
diverge run providers edit '{"identity":{"issuer":"…","subject":"github.12345.provider"},"announcement":null}'
# An incoming provider's source IPs: a value replaces them, null admits any IP.
diverge run providers edit '{"identity":{"issuer":"…","subject":"edge-provider"},"ips":[{"type":"cidr","cidr":"10.0.1.0/24"}]}'
# -> "edited" | "not_found" | "forbidden" | {"error":…}
diverge run providers disable '{"identity":{"issuer":"…","subject":"github.12345.provider"}}' # -> "done" | "not_found" | "forbidden"
diverge run providers enable '{"identity":{"issuer":"…","subject":"github.12345.provider"}}' # -> "done"
diverge run providers tag '{"identity":{"issuer":"…","subject":"github.12345.provider"},"tags":["gpu"]}' # -> "tagged"
diverge run providers untag '{"identity":{"issuer":"…","subject":"github.12345.provider"},"tags":["gpu"]}' # -> "untagged"
diverge run providers delete '{"identity":{"issuer":"…","subject":"github.12345.provider"}}'
# -> "deleted" | "not_found" | "enabled" | "in_use" | "forbidden" | {"error":…}
```
What `edit` takes: `identity` (names the record), `announcement`, `ips`, `accept_daemons`, `messageable`,
`description`. Nothing else: a body naming any other member, `direction` and `address` included, fails
to parse.
- **Three-way members.** `announcement` and `ips`: member absent = leave as is, `null` = clear (not
announced; any IP), a value = set. `accept_daemons`, `messageable` and `description`: absent = leave,
a value = set.
- **Fixed for the record's life:** the identity, the direction (incoming or outgoing) and an outgoing
record's `address`. A provider reached another way is a `disable`, a `delete` and an `add`.
- **`ips` belongs to an incoming record.** `ips` (a value or `null`) on an outgoing record is refused with
an `error`, and nothing changes.
- **An edit does not close the provider's connection**, and no container stops. The daemon changes what it
holds open on the live connection to match the record:
| Changed | What happens on the live connection |
|---|---|
| `announcement` set or replaced | The daemon stops announcing and announces again with the new text. Watchers of `providers daemons list` see it `removed`, then `added`. |
| `announcement` cleared (`null`) | The daemon stops announcing; it leaves the provider's listing. |
| `messageable` → `true` / `false` | The daemon starts / stops listening for messages on that provider. |
| `accept_daemons` → `true` | The daemon starts accepting other daemons through that provider. |
| `accept_daemons` → `false` | The daemon stops accepting; **every daemon connection that came in through that provider is dropped at once** (relays into this daemon and connected tools held from it fail until it accepts again). The provider's own connection stays. |
| `description` | Nothing. |
| `ips` | Nothing, unless the live connection is incoming and its source IP is no longer admitted: then, and only then, the connection is closed. |
Pitfalls, all of which stop running work:
- **`edit` whose new `ips` no longer admit the connected provider's source address closes that
connection.** Every agent and tool container running on it ends (its log's `undeployed` carries
`reason: "provider_edited"`). The provider is admitted again when it dials from an admitted IP. No other
edit closes the connection.
- **`disable` takes down every run on the provider** (`reason: "provider_disabled"`), stops the dial and
refuses a dial in. `enable` dials or admits it again; containers start again on their next use.
- **`delete` stops nothing and so refuses to**: it answers `enabled` unless the record is disabled first,
and `in_use` while any agent or tool is pinned to the provider or mounts its volumes. Deleting also
drops the tags the daemon kept on that provider's volumes.
- `enabled` is changed only by `enable` / `disable`, and tags only by `tag` / `untag`, never by `edit`.
- Grants: `get`, `list`, `edit`, `enable`, `disable`, `delete` over providers, and the tagging shape; a
providers grant's `within` is `"any"` or a tags test over the record's tags.
### Announced, accepting, messageable
Each is a setting of one provider's record, and each is independent of the other two.
- **Announced** (`announcement` present): the provider lists this daemon, with that text, to every party
connected to it, for as long as the daemon is connected and the record has an announcement. It is what
lets another daemon **find** this one there (`providers daemons list`), and so what a remote daemon
record or a `providers daemons message` reaches it by. Without an announcement the daemon uses the
provider but is not in its listing.
- **Accepting** (`accept_daemons: true`, the default): other daemons may connect to this daemon through
that provider. `false`: no daemon reaches it, or the tools it serves, through that provider.
- **Messageable** (`messageable: true`): the daemon listens for direct messages on that provider, from
the moment it connects, whether or not any client runs `providers daemons listen`.
For another daemon to **reach** this one through a provider (relay, connected tools), this daemon must be
both announced and accepting there. For another daemon to **message** this one with
`providers daemons message`, it must be both announced and messageable there. A daemon **sends** messages
through any connected provider that relays them, whatever its own three settings are.
The `announcement` is not the record's `description`: the description is your own note about the
provider and is never sent anywhere. There is no daemon-wide description any more, and no
`accept_daemons` in `daemon.yaml`: both are per provider record, changed by `providers edit` with no
restart.
## 2. Peers through providers (`diverge run providers daemons …`)
```bash
diverge run providers daemons list
# {"added":{"issuer":"https://identity.diverge.network","subject":"github.12345.daemon-b",
# "providers":[{"provider":{"issuer":…,"subject":"github.12345.provider"},"ip":"127.0.0.1","address":null,"listening":false}],
# "announcements":["daemon B"]}}
# "listed"
```
- One item per identity **announced** on any **connected** provider, with every route to it: each
`providers` entry (a "via") names the provider, the `ip` of the identity's connection to that provider,
the `address` the provider dialled it at (absent if the identity dialled the provider), and `listening`
(whether it listens for direct messages there).
- `announcements` holds every distinct announcement the identity is listed with on those providers (equal
texts once). It is never empty: a party is listed only while it announces itself.
- **This daemon's own identity is never listed**, whether or not it announces itself. An empty listing
means no *other* announced party shares a connected provider with this daemon. This daemon does not
need an announcement of its own to list others.
- The item's `issuer` and `subject` are what a `daemons add` names as `daemon`.
- `--watch` keeps it open (`added` / `changed` / `removed` as peers come and go). `count` caps it.
- Grant: `{"providers_daemons":{"actions":["list"],"within":"any"}}`. Only routes through providers the
grant reaches are shown.
### Direct messages
A daemon can send another party an opaque message through a shared provider. Neither the daemon nor the
provider reads the body. This needs the provider to relay messages at all (`messages:` in
`provider.yaml`; without it both requests are answered unsupported).
- **To receive**, a daemon's record of the provider must have `messageable: true`.
- **To be found by a sender's `providers daemons message`**, the receiver must also be announced there
(`announcement` present): the sending daemon finds the receiver through the provider's listing, so an
unannounced receiver answers `not_found` even while it listens.
- **To send**, a daemon needs neither: it sends through a provider whether or not it is announced or
messageable there. The provider's rate limit applies to every send.
```bash
# Receiver: listen. Runs until the command is ended; prints each message as it arrives.
diverge run providers daemons listen
# {"message":{"provider":{…},"from":{"issuer":…,"subject":"github.12345.daemon-a"},"body":"aGVsbG8="}}
# {"skipped":{"count":3}} <- this listener fell behind and missed 3
# Sender: body is standard base64.
diverge run providers daemons message \
'{"to":{"issuer":"https://identity.diverge.network","subject":"github.12345.daemon-b"},"body":"'"$(printf hello | base64)"'"}'
# -> "delivered" | "not_listening" | "not_found" | "forbidden" | {"error":…}
```
- `listen` hears the messages that arrive through the daemon's **messageable** providers; with none
messageable it hears nothing. Every listener hears every message.
- The daemon listens upstream on every connected messageable provider for as long as it is connected,
whether or not a client is listening, and keeps the latest 256 messages. A peer's `listening` flag in
`providers daemons list` therefore says "that daemon is messageable on this provider", not "someone is
running `listen` there".
- `message`: the daemon picks the provider (one where the receiver listens and that the caller's grant
reaches). `delivered` means the receiving **daemon** took it, whether or not one of its clients was
running `listen` at that moment. `not_listening`: the identity is listed but listens nowhere reachable
(it is not messageable there). `not_found`: no connected provider lists the identity (it is not
announced on a provider this daemon shares with it). When every candidate
provider is over its rate, the message waits; use `--timeout` to bound it.
- Grants: `listen` and `message` under `providers_daemons`.
## 3. Remote daemon records (`diverge run daemons …`)
A record says: *that* daemon (`daemon`, the identity it answers as), reached as *this* account of ours
(`identity`, one of this host's signed-in identities, from any issuer), by *these* routes. It is known by
its **DaemonId**: a base62 string of 1 to 11 characters that is the hash of `daemon`, `identity` and the
three route filters. There are no names.
```bash
diverge run daemons add '{"daemon":{"issuer":"https://identity.diverge.network","subject":"github.12345.daemon-b"},
"identity":{"issuer":"https://identity.diverge.network","subject":"github.12345.daemon-a"},
"description":"daemon B","tags":["peer"]}'
# -> {"added":"3kTq9ZbW1xY"} | {"exists":"3kTq9ZbW1xY"} | "forbidden" | {"error":…}
# Capture the ID either way:
ID_B="$(diverge run daemons add --jq '.added // .exists' '{…}' | tr -d '"')"
# With route filters (all optional; absent or empty = any route):
diverge run daemons add '{"daemon":{…},"identity":{…},
"providers":[{"issuer":"https://identity.diverge.network","subject":"github.12345.provider"}],
"ips":[{"type":"cidr","cidr":"10.0.0.0/8"}],
"addresses":["10.0.0.5:14980"]}'
diverge run daemons get '{"id":"3kTq9ZbW1xY"}' # {"found":{id, description, daemon, identity, providers?, ips?, addresses?, tags, created, creator, connected}}
diverge run daemons list # {"added":{…}} …, "listed"; --watch supported
diverge run daemons list '{"connected":true,"issuers":["https://identity.diverge.network"]}'
diverge run daemons edit '{"id":"3kTq9ZbW1xY","description":"daemon B (staging)"}' # "edited" | "not_found"
diverge run daemons tag '{"id":"3kTq9ZbW1xY","tags":["staging"]}' # "tagged"
diverge run daemons untag '{"id":"3kTq9ZbW1xY","tags":["staging"]}' # "untagged"
diverge run daemons delete '{"id":"3kTq9ZbW1xY"}' # "deleted" | "not_found" | "in_use" | "forbidden"
```
Rules:
- **The ID is the target.** Only the description and tags ever change. To reach elsewhere, as another
account, or by other routes: delete and add, which gives another ID. `edit` takes `description` only;
any other member fails to parse.
- Adding the same `daemon` + `identity` + routes again answers `exists` with the same ID. Several records
may name the same remote (another account of ours there, or other routes).
- `identity` and `daemon` may be from different issuers. `identity` must be signed in on this daemon's
host (`diverge run identities list`).
- **Nothing connects at `add`**, and nothing is checked: a provider named in `providers` need not be
connected. The first relay or connected tool naming the record connects; `connected` in a list says
whether a connection is held now. One connection per record, reused.
- **Routes** are filters over the vias `providers daemons list` shows for the remote: `providers` (the via's
provider is one of them), `ips` (the via's `ip` is in one of them), `addresses` (the via's `address` is
exactly one of them; a via with no address passes no `addresses` filter). A route must pass every filter
given. One passing route is chosen at random; if none passes, the remote is not reached, with no fallback.
- `delete` answers `in_use` while a connected tool names the record, or an agent's or a standalone tool's
FUSE mount does; delete those tools, or take the mounts out, first. Deleting drops a held connection.
- Grants: `{"daemons":["add"]}`; `get`, `list`, `edit`, `delete`, `relay` over daemons. `relay` is the one
grant to **use** a remote daemon: relaying a request, holding a connected tool on it, FUSE-mounting a
volume on it, and asking it for images
(`within` filter members `ids`, `issuers`, `creators`, `connected`, tags, created range); tagging shape.
- There is no `daemons accept` or `daemons connections` request. Whether a daemon accepts other daemons
through a provider is `accept_daemons` on its record of that provider (default `true`).
### What daemon B needs before A can reach it
1. A and B are connected to a **common provider**, at the daemon's own version.
2. On **B**, that provider's record has an **`announcement`** (so `providers daemons list` on A shows B).
3. On **B**, that provider's record has `accept_daemons: true` (the default).
4. B has an **account** for the identity A presents (the record's `identity`). **B's administrators do
not count here**: a daemon reaching another is admitted only as an account. Give that account roles for
exactly what A should be able to do on B.
5. That account is not already in use by another daemon connection: an account has at most one daemon
connecting as it at a time, and a second is refused.
6. A's host holds the `identity` signed in. B keeps no list of trusted issuers: its account (item 4) is what
admits that identity.
## 4. `relay`: serving a request on another daemon
Every request body may carry `relay`, an array of DaemonIds. Absent or empty, the daemon dialled serves
the request itself.
```bash
diverge run agents list '{"relay":["3kTq9ZbW1xY"]}' # B's agents, as our account on B
diverge run info '{"relay":["3kTq9ZbW1xY"]}' # B's version: the cheapest reachability test
diverge run agents message '{"agent":{"name":"echo"},"type":"chat","content":[{"type":"text","text":"hi"}],"relay":["3kTq9ZbW1xY"]}'
diverge run agents list '{"relay":["3kTq9ZbW1xY","7Qm2"]}' # two hops: A -> B -> C; "7Qm2" is B's record of C
```
How it is served:
1. The daemon that reads a request with `relay` does not serve it. It takes the **first ID** off, finds
*its own* record of that ID, and checks one thing: the caller holds `relay` over that record
(`{"daemons":{"actions":["relay"],"within":"any"}}`).
2. It connects to that remote (or reuses the record's connection) **as the account the record names**, and
puts the request there with the first ID removed.
3. The remote judges what is left: the next ID, if any, as that account's `relay` over *its* record; and
finally the request itself, **by that account's roles on the remote**. The remote sees an ordinary
request from that account and nothing about who originally sent it.
4. The relaying daemon is a pure conduit: every answer, channel and stream comes back unchanged, so
streams, `--watch`, uploads, downloads, exec, terminals and MCP connects all work through a relay.
Consequences:
- **Your identity on the remote is the record's `identity`, not you.** Things created through a relay have
that account as their creator there. Being an administrator on A means nothing on B.
- A refusal looks like the request's own answer: `"forbidden"` (no `relay` grant here, or the remote
account lacks the grant for the request) or `{"error":…}` (no record of that ID, the remote not announced
or not reachable, its handshake refused, or the connection lost mid-request). The same `forbidden` can
come from either daemon; check the local `relay` grant first, then the remote account's roles.
- IDs are per daemon: the second ID of a two-hop relay is a record held by the *first* remote. List them
with `diverge run daemons list '{"relay":["<first id>"]}'`.
- An old ID finds nothing after its record is deleted and re-added differently.
## 5. Connected standalone tools (`diverge run connected-standalone-tools …`)
A connected tool is a standalone tool that **another daemon** holds and runs, held here under a local name
so this daemon's agents can call it. This daemon never starts, stops, edits or inspects the container: its
image, limits, files, exec, terminal and frontend all belong to the other daemon. Here it can only be
named, attached to agents, tagged, logged and deleted.
```bash
# Hold B's tool "notebook" here as "b-notebook". Connects nothing yet.
diverge run connected-standalone-tools create \
'{"daemon":"3kTq9ZbW1xY","tool":{"name":"notebook"},"name":"b-notebook"}'
# -> "created" | "in_use" (name taken) | "forbidden" | {"error":…} (no record of that ID)
# The tool may be named on the remote by template and index instead, and may lie further away:
# "tool":{"template":"<template id on B>","index":1}
# "route":["7Qm2"] <- B's record of C; the tool is on the last daemon of daemon + route
diverge run connected-standalone-tools get '{"tool":{"name":"b-notebook"}}' # {"found":{…}}
diverge run connected-standalone-tools list # --watch supported
diverge run connected-standalone-tools list '{"daemons":["3kTq9ZbW1xY"],"deployed":true}'
diverge run connected-standalone-tools attach-agent-instance '{"tool":{"name":"b-notebook"},"agent":{"name":"echo"}}'
diverge run connected-standalone-tools attach-agent-template '{"tool":{"name":"b-notebook"},"template":"<agent template id>"}'
# -> "attached" | "no_tool" | "no_agent" / "no_template" | "forbidden"
diverge run connected-standalone-tools detach-agent-instance '{"tool":{"name":"b-notebook"},"agent":{"name":"echo"}}'
diverge run connected-standalone-tools detach-agent-template '{"tool":{"name":"b-notebook"},"template":"<agent template id>"}'
# -> "detached" | "no_tool" | "no_agent" / "no_template" | "forbidden"
# Rename (JSON Patch over {"name":…}; null = no name)
diverge run connected-standalone-tools edit '{"tool":{"name":"b-notebook"},"patch":[{"op":"replace","path":"/name","value":"notes"}]}'
# -> "edited" | "not_found" | "in_use" | "forbidden"
diverge run connected-standalone-tools tag '{"tool":{"name":"notes"},"tags":["shared"]}' # "tagged"
diverge run connected-standalone-tools untag '{"tool":{"name":"notes"},"tags":["shared"]}' # "untagged"
diverge run connected-standalone-tools delete '{"tool":{"name":"notes"}}'
# -> "deleted" | "not_found" | "attached" (detach everywhere first) | "forbidden"
diverge run logs '{"of":{"type":"connected_standalone_tool","name":"notes"}}' # every call routed into it
```
What to know:
- **Naming the tool.** A connected tool is referenced by `{"name":…}` or, once and for all, by
`{"daemon":"<id>","tool":<the tool as the remote names it>,"index":<n>}` (the list item carries all
three). Names are one namespace across this daemon's standalone *and* connected tools. A tool created
without a name is reachable only by the long form.
- **`create` checks nothing on the remote.** A remote that is unreachable, or that has no such tool or does
not allow it, is not the create's error: the tool simply shows `deployed: false` and the agent's calls to
it fail. Verify the name first through a relay: `diverge run standalone-tools list '{"relay":["<id>"]}'`.
- **One connect per tool, opened on use.** Attaching connects nothing. When an attached agent first calls
the tool, this daemon connects to the remote (as the record's account) and opens that daemon's
`standalone-tools connect` on the tool; the remote starts the container if needed and holds it while
connected. The connect is let go after `idle_seconds` without use. `deployed` = the connect is held;
`active` = a call is in flight.
- **Attaching works on a running agent**: the tool appears in its tool list at once and the agent is told
its tool list changed. An agent attached both directly and through its template has the tool once.
Attach and detach are idempotent.
- **Fixed at create:** `daemon`, `route` and `tool`. `edit` changes the name only.
- A list item: `name`, `daemon`, `route`, `tool`, `index`, `creator`, `created`, `active`, `last_active`,
`deployed`, `last_deployed`, `attached_agent_instances`, `attached_agent_templates`, `tags`. Filter
members: `names`, `daemons`, `creators`, `active`, `deployed`, `attached_agent_instances`,
`attached_agent_templates`, tags, created range, `count`.
- No request of the `standalone-tools` family finds a connected tool, and none here finds a standalone one.
Grants needed:
| Where | Who | Grant |
|---|---|---|
| This daemon | the caller of `create` | `{"connected_standalone_tools":["create"]}` and `relay` over the daemons record |
| This daemon | the caller of an attach / detach | `attach` / `detach` over the connected tool, and `edit` over the agent (or `attach` over the agent template) |
| Remote daemon | the account the record names | `{"standalone_tools":{"actions":["connect"],"within":…}}` reaching the tool; for a `route`, `relay` over each further record on each hop |
## 5b. Mounting a volume that is on another daemon
An agent or a standalone tool on this daemon can FUSE-mount a file or a directory of a volume that belongs
to a provider of **another daemon's**. The mount entry names the remote daemon:
```json
"fuse_directory_mounts": [
{"daemon": "3kTq9ZbW1xY", "route": [],
"provider": {"issuer": "…", "subject": "github.12345.provider-of-b"},
"volume_name": "shared", "volume_relative_path": [],
"volume_mode": "read_only", "container_path": ["shared"]}
]
```
- `daemon` is this daemon's record of the remote; `route` (optional) names further records beyond it, each
on the daemon before, exactly as a connected tool's `daemon` and `route` do. A `route` without a `daemon`
is the create's error. `provider` and `volume_name` name the volume **as the last daemon names it**.
- **The create checks one thing: `relay` over the `daemon` record.** It does not look at the remote volume,
its provider, its path or its mode. A wrong name is not the create's error.
- **At the container's start** this daemon opens the remote's `volumes fuse_serve` of the volume, as the
account the record names, and forwards every file operation to it. The remote refuses with its own
answers (`forbidden`, `not_found`, `mounted`, `fuse_served`, `held`, a mode mismatch, `unsupported`); any
of them is the start's error, in the agent's or tool's log.
- **The account on the remote needs `fuse_serve` over the volume there**:
`{"volumes":{"actions":["fuse_serve"],"within":…}}`. `mount` there is not enough. For a `route`, the
account at each hop needs `relay` over the next record.
- While the serve is open the remote counts the volume as in use: `volumes delete` there answers `in_use`
and the at-rest requests answer `held`.
- **A lost serve ends the run.** If the connection to the remote daemon ends at any hop, or the remote's
provider goes, the container is stopped and the run ends as `undeployed` with reason `mount_lost`. The
same now holds for a FUSE mount of a local provider's volume whose provider goes.
- `diverge run volumes fuse-serve` exists as a command so its `request-schema` and `response-schema` can be
read, but the request itself is refused by the CLI: it holds a scope open and answers a filesystem, which
a command cannot do. It is what one daemon asks of another.
- Dependency tools cannot mount from another daemon; they mount only from their agent's container.
## 6. Worked example: A records B, relays, and holds B's tool
Daemon A is the CLI's default daemon; daemon B is `--daemon b` in `cli.yaml`. Both are connected to one
provider, and each has an `announcement` on its record of it. A's daemon presents `github.12345.daemon-a`; B's presents `github.12345.daemon-b`. You are an
administrator on both. (This is step 10 of `reports/SETUP_INSTRUCTIONS_1.md`.)
```bash
ISS=https://identity.diverge.network
# --- On B: a role and an account for the identity A will present. B's admins do not count for A.
diverge run --daemon b roles create '{"name":"peer","description":"daemon A on this daemon","grants":[
{"agents":{"actions":["get","list","logs","message"],"within":"any"}},
{"agents_templates":{"actions":["get","list"],"within":"any"}},
{"standalone_tools":["create"]},
{"standalone_tools":{"actions":["get","list","logs","connect"],"within":"any"}},
{"standalone_tools_templates":["create"]},
{"standalone_tools_templates":{"actions":["get","list"],"within":"any"}},
{"events":["list"]},
{"providers":{"actions":["read"],"within":"any"}}]}'
diverge run --daemon b accounts create '{"identity":{"issuer":"'$ISS'","subject":"github.12345.daemon-a"},"roles":["peer"]}'
# --- On A: is B visible through a shared provider?
diverge run providers daemons list --jq '.added? | {subject, via: [.providers[].provider.subject]}'
# {"subject":"github.12345.daemon-b","via":["github.12345.provider"]} (A itself is never listed)
# --- On A: record B, reached as github.12345.daemon-a.
ID_B="$(diverge run daemons add --jq '.added // .exists' \
'{"daemon":{"issuer":"'$ISS'","subject":"github.12345.daemon-b"},"identity":{"issuer":"'$ISS'","subject":"github.12345.daemon-a"},"description":"daemon B"}' | tr -d '"')"
# --- Relay: A forwards, B serves as github.12345.daemon-a's account.
diverge run info '{"relay":["'$ID_B'"]}' # {"info":{"version":"…"}}
diverge run agents list '{"relay":["'$ID_B'"]}' # B's agents (or just "listed"); not "forbidden"
diverge run daemons get '{"id":"'$ID_B'"}' --jq '.found.connected' # true once the first relay connected
# --- A tool on B, made through the relay (creator there: github.12345.daemon-a's account).
TPL="$(diverge run standalone-tools templates create --jq '.created // .exists' \
'{"type":"tool","mode":"transient","image":{"digest":"sha256:<digest>","references":[{"registry":"docker.io","name":"diverge-local/memory"}]},
"memory":268435456,"disk":268435456,"arguments":{},"relay":["'$ID_B'"]}' | tr -d '"')"
diverge run standalone-tools create '{"template":"'$TPL'","name":"notebook","relay":["'$ID_B'"]}'
# --- Hold B's tool on A, attach it to A's agent "echo", use it.
diverge run connected-standalone-tools create '{"daemon":"'$ID_B'","tool":{"name":"notebook"},"name":"b-notebook"}'
diverge run connected-standalone-tools attach-agent-instance '{"tool":{"name":"b-notebook"},"agent":{"name":"echo"}}'
diverge run agents message '{"agent":{"name":"echo"},"type":"chat","content":[{"type":"text","text":"remember that the launch is on Friday"}]}'
# --- See what happened.
diverge run logs '{"of":{"type":"agent","name":"echo"}}' # the agent's side
diverge run logs '{"of":{"type":"connected_standalone_tool","name":"b-notebook"}}' # every call A routed into B's tool
diverge run connected-standalone-tools get '{"tool":{"name":"b-notebook"}}' --jq '.found | {deployed, active, last_deployed}'
diverge run logs '{"of":{"type":"standalone_tool","name":"notebook"},"relay":["'$ID_B'"]}' # B's own log of the tool
```
Template and tool bodies are covered in `diverge-tools`; image digests in `diverge-images`.
## Troubleshooting
| Symptom | Likely cause |
|---|---|
| Provider record stays `disconnected` | Provider down or wrong `address`; daemon not in the provider's `incoming`; no `identity` in `daemon.yaml` or `provider.yaml`, or it is not signed in; record disabled. |
| Provider is `different_version` | Daemon and provider builds differ; the provider is held but unused. Reinstall so both match. |
| Containers died after a provider edit | The edit set `ips` that no longer admit the incoming provider's source address: the connection was closed (`undeployed` with `provider_edited`). No other edit closes it. They start again on next use, once the provider is connected again. |
| `providers edit` answers a parse error | The body names a member `edit` does not take: `direction`, `address`, `listable`, `enabled`, `tags`. Only `identity`, `announcement`, `ips`, `accept_daemons`, `messageable`, `description`. |
| `providers daemons list` is empty on A | B's record of the shared provider has no `announcement`; A and B share no connected provider; A's grant reaches no provider. A never lists itself. |
| Relayed request answers `{"error":…}` | No record of that ID; B not announced on a provider A is connected to by a route the record allows; B has no **account** for the identity presented (admins do not count); B's record of that provider has `accept_daemons: false`; the account is already held by another daemon connection; the identity is not signed in on A's host. |
| Relayed request answers `"forbidden"` | Caller lacks `relay` over the record on A, or the account on B lacks the grant for the request itself. |
| Connected tool never `deployed`, agent's calls fail | Wrong tool name on B; B's account lacks `connect` over that tool; B unreachable. Check with a relayed `standalone-tools get`. |
| `daemons delete` answers `in_use` | A connected tool names the record, or an agent's or tool's FUSE mount does. |
| A run ends `undeployed` with reason `mount_lost` | A FUSE mount's serve ended under the running container: the link to the volume's daemon dropped at some hop, or the volume's provider went. Restore the link and message again. |
| A container with a remote FUSE mount fails at start | The account on the remote lacks `fuse_serve` over the volume; wrong provider or volume name there; the volume is in another mode; the remote is unreachable. Read the start error in the log. |
| `message` answers `not_listening` | The receiving daemon's record of the shared provider is not `messageable: true`, or the provider relays no messages. |
| `message` answers `not_found` | The receiver is not announced (no `announcement`) on a provider this daemon is connected to and the grant reaches. It may be listening all the same: the sender finds it through the listing. |
| `listen` prints nothing | No connected provider's record is `messageable: true`. |
## Not verified
- **Daemon-to-daemon has never been run live**: remote records connecting, `relay` (single or multi-hop),
connected standalone tools (create, attach, calls, logs), `route` on a connected tool, and FUSE mounts of
a volume on another daemon (`volumes fuse_serve`). Everything in
sections 3 to 6 is from the SDK, the daemon source, the CLI schemas and
`reports/SETUP_INSTRUCTIONS_1.md` step 10, which itself says to expect debugging.
- **Direct messages** (`providers daemons listen|message`) and incoming-direction providers have not been
run live either.
- **The per-provider settings** (`announcement`, `accept_daemons`, `messageable`) and what `providers edit`
does to a live connection are from the SDK's request types and the daemon source; no edit has been run
against a connected provider.
- Live-checked while writing this (read-only, as an administrator): `providers list` with one connected
outgoing provider (the status, capabilities and capacity shapes above are real), `providers daemons list`,
`daemons list` and `connected-standalone-tools list` answering `"listed"` with nothing held.
- Whether a tool on B created by someone other than the relayed account can be held: the source judges the
remote `connect` by the account's grant reach over the tool (not by who created it), so a
`within: "any"` connect grant should reach any standalone tool on B. Not exercised.
- The exact example ID `3kTq9ZbW1xY`, the peer listing output and the `messages` capability shape are
illustrative.
## When this task is done
Load the `diverge` skill again before starting the next Diverge task: it is the index, and it says which
skill the next task needs.