From 0e0f404f0f63feabff385fd9d0f73d61376435c0 Mon Sep 17 00:00:00 2001
From: Adeel Ahmad
Date: Sun, 18 Oct 2026 14:08:13 +0000
Subject: [PATCH] feat(mesh): agents manage the mesh's nodes over MCP and in
the assistant
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
An admin's agent now does what Settings › Nodes and Network do. `mesh` reads the mesh: on or off, the CA's
fingerprint and expiry, this machine's mesh address, every machine with how it's doing, and the join tokens not
used yet, never their secrets. `add_mesh_node` makes a join token and its install line (turning the mesh on when
it's off), `change_mesh_node` renames a machine or changes its namespaces, `remove_mesh_node` and
`restore_mesh_node` take one off and bring it back, and `withdraw_mesh_token` withdraws a token.
Over MCP every change needs an admin's write-scope token, happens at once and is audited as the web app's are. In
the assistant, adding a machine and taking one off always wait for the person's yes; the rest happens at once
unless the answer read outside text. An approved install line goes to the person once, on the approval card, and is
kept out of the approval's stored result, the audit log and the model's context.
The route, MCP and the assistant share mesh.add (token, line, turning the mesh on) and mesh.check_token, so the
assistant says what's wrong with a token's terms before it asks.
Co-Authored-By: Claude Opus 5.5 (1M context)
Claude-Session: https://claude.ai/code/session_01GTrHPwWHtEvFJFq3M1YpH4
---
README.md | 5 +-
changelog.d/mesh-tools.md | 7 +
docs/assistant.md | 9 +-
docs/mcp.md | 13 +-
docs/mesh.md | 26 +-
docs/requirements.md | 1 +
fastapi_backend/app/api/mcp_tools.py | 141 ++++++++++-
fastapi_backend/app/api/v1/routes/chats.py | 3 +-
fastapi_backend/app/api/v1/routes/mesh.py | 15 +-
fastapi_backend/app/domain/ai_tools.py | 4 +-
fastapi_backend/app/domain/bridge.py | 9 +-
fastapi_backend/app/domain/mesh.py | 84 ++++++-
fastapi_backend/app/domain/ops_tools.py | 191 ++++++++++++++-
fastapi_backend/app/schemas/chats.py | 3 +
fastapi_backend/tests/api/test_approvals.py | 10 +-
fastapi_backend/tests/api/test_mcp.py | 5 +
fastapi_backend/tests/api/test_mesh_agents.py | 224 ++++++++++++++++++
.../__tests__/approval-install-line.test.tsx | 70 ++++++
.../app/openapi-client/types.gen.ts | 6 +
nextjs-frontend/components/chat/approval.tsx | 30 ++-
.../components/settings/mesh-nodes.tsx | 7 +-
nextjs-frontend/openapi.json | 12 +
threat-model.json | 6 +-
threat-model.md | 2 +-
threat-model.yaml | 8 +-
25 files changed, 846 insertions(+), 45 deletions(-)
create mode 100644 changelog.d/mesh-tools.md
create mode 100644 fastapi_backend/tests/api/test_mesh_agents.py
create mode 100644 nextjs-frontend/__tests__/approval-install-line.test.tsx
diff --git a/README.md b/README.md
index 4b718fed1..cd3e92878 100644
--- a/README.md
+++ b/README.md
@@ -248,8 +248,9 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p
Lens joins it over a private network of its own, a Nebula mesh it issues the certificates for: one install line
with a one-time token, and the machine needs nothing else. Worker nodes run jobs as their own user of the
database, never with Lens's keys; compute nodes run the assistant's code on a sandbox gateway of their own.
- Settings › Nodes and Network show each machine and the mesh, and agents do the same over the API. Not yet tried
- between two real machines. ([Nodes and the mesh](docs/mesh.md); [checks](docs/requirements.md#run-on-more-machines))
+ Settings › Nodes and Network show each machine and the mesh, and agents do the same over the API, MCP and the
+ assistant. Not yet tried between two real machines. ([Nodes and the mesh](docs/mesh.md);
+ [checks](docs/requirements.md#run-on-more-machines))
- **Keep it up to date and backed up.** Lens checks for a new release once a day and tells admins by email or a
notification. One click in Settings › Updates (or one API call) upgrades it through a small agent on the machine,
showing each step, and rolls back when the new version doesn't start; nothing installs unless an admin says so. The
diff --git a/changelog.d/mesh-tools.md b/changelog.d/mesh-tools.md
new file mode 100644
index 000000000..803da79f0
--- /dev/null
+++ b/changelog.d/mesh-tools.md
@@ -0,0 +1,7 @@
+- **Agents manage the mesh's machines** (in progress, as the mesh is). Over MCP and in the assistant, an admin's agent
+ reads the mesh (`mesh`: its CA, this machine's address, every machine and how it's doing, the join tokens not used
+ yet, never their secrets) and adds a machine (`add_mesh_node`, which answers with the install line), renames one or
+ changes its namespaces, takes one off and brings it back, and withdraws a join token. In the assistant, adding a
+ machine and taking one off always wait for your yes, and the install line is shown to you once on the approval
+ card, never kept or sent to the model; the rest happens at once. Over MCP every change needs an admin's
+ write-scope token and is audited ([Agents](docs/mesh.md#agents)).
diff --git a/docs/assistant.md b/docs/assistant.md
index 765c87be2..6073b9c8b 100644
--- a/docs/assistant.md
+++ b/docs/assistant.md
@@ -980,12 +980,17 @@ Admins also get the server tools: `server_status` (what's set up and what's miss
and the items they can refer to, never a value), the news feed tools: `news_feeds`, `subscribe_feed` (follow a feed into a namespace in one step,
[News feeds](processing.md#news-feeds-rss-and-atom)) and `unsubscribe_feed`, and the people tools: `list_people`, `invite_person` (an account, optionally with a role in one
namespace; Lens emails the sign-in link when mail is set up) and `change_person` (a role in a namespace, or disabling
-and enabling an account). Removing an account for good stays in the web app and the API. In an ordinary conversation
+and enabling an account). Removing an account for good stays in the web app and the API. The mesh tools manage the
+machines Lens runs on ([Nodes and the mesh](mesh.md#agents)): `mesh` reads it, `add_mesh_node` makes the install line
+for another machine (shown to the person on the approval card, once), `remove_mesh_node` takes one off, and
+`change_mesh_node`, `restore_mesh_node` and `withdraw_mesh_token` rename a machine or change its namespaces, bring a
+removed one back, and withdraw a join token, at once. The [auto scaling](scaling.md#agents) tools are here too. In an ordinary conversation
their changes are approval cards. In a **setup conversation**
(`POST /api/v1/chats` with `"kind": "setup"`, or **Finish with the assistant** in the setup wizard once a model is
connected) the admin has asked the assistant to set the server up, so it makes the changes itself and says what it
changed. Every change is audited with `assistant` in its detail, and all of them stay changeable in Settings.
-Turning telemetry on or off, changing the Secrets section, inviting people and changing their access always ask first, and so does every change once the answer has read text from outside
+Turning telemetry on or off, changing the Secrets section, inviting people and changing their access, and adding a
+machine to the mesh or taking one off always ask first, and so does every change once the answer has read text from outside
Lens ([third-party content](#third-party-content-and-prompt-injection)).
### Routine choices
diff --git a/docs/mcp.md b/docs/mcp.md
index 52eef726c..9c88ac855 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -45,8 +45,8 @@ Each namespace can have its own server, at `/mcp/` (`https://lens.exa
that should see that namespace and nothing else: a family assistant, a project's coding agent, a client's app. It
has the same tools, but sees only that namespace, whatever else the person who signs the agent in can read. Tools
that take a namespace use this one when none is named, `list_namespaces` and `list_files` show only it, and the tools
-about the server itself (`file_storage`, `monitoring`, `services`, `mcp_servers`, `sandbox_gateway`, `install_settings`
-and the ones that change them) aren't there, even for admins. Nor are the person's own conversations (`list_chats`,
+about the server itself (`file_storage`, `monitoring`, `services`, `mcp_servers`, `sandbox_gateway`, `install_settings`,
+`mesh` and the ones that change them) aren't there, even for admins. Nor are the person's own conversations (`list_chats`,
`read_chat`, `rename_chat`, `export_chat`) and projects (`list_projects`, `read_project`, `create_project`,
`update_project`, `schedule_project`), which belong to no namespace. An admin counts as an owner of the namespace there.
@@ -164,6 +164,11 @@ For an app that speaks OpenAI's API rather than MCP, the namespace can also answ
| `install_plugin` | install one as your own extension, private until you share it, or bring yours to the version listed now; `preview` installs nothing and says what it would add and what Lens leaves out. Needs a write-scope token |
| `install_settings` | whether other devices on the network reach Lens and its edition (full or lean), whether the machine's upgrade agent can change them, and the install line to run when it can't. Admins only |
| `set_install_settings` | open Lens to the network or keep it to this machine, or change the edition: the machine sets itself up again and Lens restarts ([Updates](updates.md#setting-the-machine-up-again)). Admins only, with a write-scope token |
+| `mesh` | Lens's network between its machines ([Nodes and the mesh](mesh.md#agents)): whether it's on, its CA, this machine's address, every machine and how it's doing, and the join tokens not used yet, never their secrets. Admins only |
+| `add_mesh_node` | add a machine: a join token and the install line to run on it, shown once; turns the mesh on. Admins only, with a write-scope token |
+| `change_mesh_node` | rename a machine or change the namespaces it serves (`every_namespace` for every one). Admins only, with a write-scope token |
+| `remove_mesh_node` | take a machine off the mesh; `restore_mesh_node` brings it back while its certificate is good. Admins only, with a write-scope token |
+| `withdraw_mesh_token` | withdraw a join token not used up yet. Admins only, with a write-scope token |
| `news_feeds` | the news feeds (RSS or Atom) Lens follows, the namespaces each brings posts into and how the last scan went; addresses stay sealed. Admins only |
| `subscribe_feed` | follow a news feed into a namespace in one step: its address or a page of the site, read first and kept only if it works; `backfill` also brings in the posts it lists now ([News feeds](processing.md#news-feeds-rss-and-atom)). Admins only, with a write-scope token |
| `unsubscribe_feed` | stop following a news feed; the posts it brought in stay. Admins only, with a write-scope token |
@@ -192,7 +197,9 @@ queues an episode, `create_feed` and `publish_to_feed`, which make and fill a [p
editors), `enhance`, which enhances an image and reads it again (the process permission),
`set_namespace_integrations`, which turns a namespace's own MCP server or chat completions on or off (owners), `set_picture_descriptions`, which changes what describes pictures (admins), `set_file_storage`, which changes where new files are kept (admins), `set_secret_reference`, which points a secret field at a password manager's item (admins), `install_plugin`, which
installs a plugin from a marketplace as your own extension, `add_mcp_server`, which adds an
-MCP server (admins), `subscribe_feed` and `unsubscribe_feed`, which follow and stop following news feeds (admins), `set_mail_routing`, which changes where an email account's messages go (admins), and `set_monitoring`, `set_service`,
+MCP server (admins), `subscribe_feed` and `unsubscribe_feed`, which follow and stop following news feeds (admins), `set_mail_routing`, which changes where an email account's messages go (admins), `add_mesh_node`,
+`change_mesh_node`, `remove_mesh_node`, `restore_mesh_node` and `withdraw_mesh_token`, which manage the machines on
+the [mesh](mesh.md#agents) (admins), and `set_monitoring`, `set_service`,
`set_sandbox_gateway` (the [code sandbox](assistant.md#code-sandbox)'s gateway) and `set_install_settings`, which have the machine change how Lens runs (admins).
Importing stays in the web app and the API.
diff --git a/docs/mesh.md b/docs/mesh.md
index d5cd1ee69..27b431016 100644
--- a/docs/mesh.md
+++ b/docs/mesh.md
@@ -4,7 +4,8 @@ Status: **in progress**. Built: Lens as the mesh's certificate authority, join t
token, each machine's Nebula config, a node's renewals and reports, removing a node, the `mesh` settings, the API
under `/api/v1/mesh`, Nebula running on the primary in the `mesh` container, relaying the database and the API,
`lens node` with the install line that joins another machine, worker nodes running jobs, compute nodes running the
-assistant's code, and Settings › Network and Nodes in the web app. Not yet tried between two real machines.
+assistant's code, Settings › Network and Nodes in the web app, and the same over MCP and in the assistant
+([Agents](#agents)). Not yet tried between two real machines.
Lens runs on one machine until you add another: a Mac with a GPU to transcribe on, a box to run the assistant's code
on, a server with more disk. Those machines talk to this install over a private network of Lens's own, a
@@ -12,7 +13,8 @@ on, a server with more disk. Those machines talk to this install over a private
between them is encrypted and signed with certificates Lens issued, and Nebula's firewall lets through only what each
role needs. A single-machine install never turns it on.
-**Off until an admin adds a node.** Adding a node (Settings › Nodes, or `POST /api/v1/mesh/tokens`) makes the mesh's
+**Off until an admin adds a node.** Adding a node (Settings › Nodes, `POST /api/v1/mesh/tokens`, or an agent's
+`add_mesh_node`) makes the mesh's
certificate authority the first time and turns `mesh.enabled` on. Nothing goes in `.env`; nothing is asked at
install.
@@ -222,6 +224,26 @@ In the web app:
asks nothing: the row stays, dimmed and marked Removed, with Undo while its certificate is good. Join tokens not
used yet are listed under it, each with Withdraw. The list refreshes every 15 seconds.
+## Agents
+
+The same for an admin's agent, over [MCP](mcp.md) and in the [assistant](assistant.md#setting-up-and-running-the-server-by-chat)
+(admins, in the server tools):
+
+| Tool | | Over MCP | In the assistant |
+| --- | --- | --- | --- |
+| `mesh` | whether it's on, the CA's fingerprint and expiry, this machine's mesh address, every machine (id, name, role, address, online and last seen, Nebula, its Lens version and machine, the namespaces it serves, on a compute node whether its sandbox gateway runs, its error, when it was removed) and the join tokens not used yet, never their secrets | reads | reads |
+| `add_mesh_node` | a join token and the install line for another machine (`role` worker or compute, optionally `name`, `namespaces`, `hours`, `uses`), shown once; turns the mesh on when it's off | at once, answering with the line | always waits for the person's yes; the line is shown to them on the approval card, once |
+| `change_mesh_node` | renames a machine or changes the namespaces it serves | at once | at once |
+| `remove_mesh_node` | takes a machine off the mesh | at once | always waits for the person's yes |
+| `restore_mesh_node` | brings a removed machine back while its certificate is good | at once | at once |
+| `withdraw_mesh_token` | withdraws a join token not used up yet | at once | at once |
+
+Over MCP the changes need an admin's token with the write scope; they're audited as the web app's are, with `mcp` in
+the detail (`mesh.token.create`, `mesh.node.change`, `mesh.node.remove`, `mesh.node.restore`, `mesh.token.withdraw`),
+and the install line uses the address the agent called Lens at. In the assistant the install line uses the web app's
+address the person is on, and it isn't kept: not in the approval, the audit log or anything the model is sent. What
+happens at once still asks first once the answer has read text from outside Lens.
+
## What keeps it safe
- Nothing listens until an admin adds a node, and single-machine installs never do.
diff --git a/docs/requirements.md b/docs/requirements.md
index c7106df0f..36d73044b 100644
--- a/docs/requirements.md
+++ b/docs/requirements.md
@@ -314,6 +314,7 @@ request, to another check that proves the same thing; loosening a requirement or
| A worker node runs jobs as its own user of Lens's database, never root and never with the archive's secret, reading only its namespaces' files over the mesh, never a vault's | [test_mesh_workers.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_mesh_workers.py) `test_a_worker_node_runs_lens_worker_as_its_own_user_of_the_database`, `test_its_jobs_read_files_from_here_over_the_mesh`, `test_a_node_serving_some_namespaces_takes_only_their_jobs`, `test_only_a_worker_node_gets_the_database`, `test_a_node_runs_only_the_steps_a_node_can` |
| A compute node runs the assistant's code on a gateway of its own, which Lens reaches over the mesh with mutual TLS, holding its certificate sealed | [test_mesh_compute.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_mesh_compute.py) `test_a_compute_nodes_install_line_starts_its_gateway`, `test_a_compute_node_hands_over_its_gateway_and_the_assistant_may_run_code_there`, `test_only_a_compute_node_gives_a_gateway_and_only_a_certificate`, `test_lens_reaches_the_nodes_gateway_with_its_certificate_checked_by_name` |
| Settings › Nodes adds a machine with Enter, shows its install line once, lists each machine with how it's doing, renames in place and removes with Undo; Settings › Network shows the mesh and its settings | [settings-mesh.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/settings-mesh.test.tsx) `adds a node with Enter and shows the install line once, with its terms`, `lists each machine with how it's doing`, `removes a node without asking, and undoes it`, `renames a node with Enter`, `says whether a compute node's sandbox gateway runs`, `shows that it runs, and what Nebula said`, `checks the network and the hosts as the server does` |
+| Agents read the mesh and add, rename, remove, restore and withdraw over MCP and in the assistant; adding or removing a machine in the assistant waits for the admin's yes, and a join token's secret never reaches the model | [test_mesh_agents.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_mesh_agents.py) `test_mcp_clients_add_and_manage_mesh_nodes`, `test_the_assistant_adds_and_removes_machines_once_the_person_approves`, `test_the_assistant_renames_restores_and_withdraws_at_once`, `test_a_setup_conversation_still_asks_before_a_machine_joins_or_goes`, `test_only_admins_get_the_mesh_tools`; [approval-install-line.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/approval-install-line.test.tsx) `shows its install line this once, until the person is done with it` |
## Keep it up to date and backed up
diff --git a/fastapi_backend/app/api/mcp_tools.py b/fastapi_backend/app/api/mcp_tools.py
index 9b66b74c5..c55ecbc2c 100644
--- a/fastapi_backend/app/api/mcp_tools.py
+++ b/fastapi_backend/app/api/mcp_tools.py
@@ -25,7 +25,7 @@
from fastapi import HTTPException, Request
from pydantic import ValidationError
-from app.api.deps import Access, Principal
+from app.api.deps import Access, Principal, web_origin
from app.api.v1.routes import activities as activity_routes
from app.api.v1.routes import automation_vars as var_routes
from app.api.v1.routes import automations as automation_routes
@@ -66,6 +66,7 @@
mail_routes,
manual,
mcp_servers,
+ mesh,
monitoring,
moondream,
notebook,
@@ -3116,6 +3117,144 @@ def terminate_scaling_unit(ctx: Context, unit_id: int, why: str | None = None) -
return _scaling_do(ctx, "terminate_scaling_unit", {"unit_id": unit_id, "why": why})
+# ---------- the mesh: Lens's machines (admins) ----------
+def _mesher(ctx: Context, write: bool = False) -> None:
+ if not ctx.user.admin:
+ raise ToolError("only admins see or change the mesh")
+ if write and not ctx.user.can_write:
+ raise ToolError("this token is read-only: ask for a token with the write scope to change the mesh")
+
+
+def _mesh_do(ctx: Context, change: Callable[[], dict[str, Any]], action: str, target: str, detail: Any = None) -> dict[str, Any]:
+ """A change to the mesh, as an admin's agent: made at once and audited, as the web app's are."""
+ _mesher(ctx, write=True)
+ try:
+ out = change()
+ except mesh.MeshError as e:
+ raise ToolError(str(e)) from None
+ auth.audit(ctx.db, ctx.user.as_audit(), action, target, {**(detail or {}), "via": "mcp"})
+ return out
+
+
+@tool(
+ "mesh",
+ "Nodes and the mesh",
+ "Lens's private network between the machines it runs on (Settings › Nodes and Network): whether it's on, its CA's "
+ "fingerprint and expiry, this machine's address on it, every machine (role worker or compute, address, online and "
+ "last seen, Nebula, its Lens version and machine, the namespaces it serves, whether a compute node's sandbox "
+ "gateway runs, its error, when it was removed) and the join tokens not used yet, never their secrets. Admins only.",
+ admin=True,
+)
+def mesh_overview(ctx: Context) -> dict[str, Any]:
+ _mesher(ctx)
+ return {**mesh.agent_view(ctx.db, ctx.cfg), "settings": f"{ctx.web}/settings/nodes"}
+
+
+@tool(
+ "add_mesh_node",
+ "Add a machine to the mesh",
+ "Let another machine join the mesh: a join token and the line to run on that machine (install_line), shown this "
+ "once, so hand it to the person and don't keep it. role worker runs jobs against this install's database (it "
+ "needs a SurrealDB server, as Docker installs have); compute runs the assistant's code in sandboxes and gets "
+ "nothing of Lens's. Makes the mesh's CA the first time and turns the mesh on. Admins only, with a token that has "
+ "the write scope.",
+ Arg("role", "string", "worker or compute", default="worker", enum=mesh.ROLES),
+ Arg("name", "string", "the name it shows as (none: the name the machine sends)", max_length=63),
+ Arg("namespaces", "string[]", "the namespaces it serves (none: every one)"),
+ Arg("hours", "integer", "how long the token can be used", default=24, minimum=mesh.TOKEN_HOURS[0], maximum=mesh.TOKEN_HOURS[1]),
+ Arg("uses", "integer", "how many machines may join with it", default=1, minimum=mesh.TOKEN_USES[0], maximum=mesh.TOKEN_USES[1]),
+ writes=True,
+ admin=True,
+)
+def add_mesh_node(
+ ctx: Context, role: str = "worker", name: str | None = None, namespaces: list[str] | None = None, hours: int = 24, uses: int = 1
+) -> dict[str, Any]:
+ _mesher(ctx, write=True)
+ base = ctx.request.app.state.archive.base
+ try:
+ made = mesh.add(ctx.db, ctx.cfg, base, ctx.user.email, role, name, namespaces, hours, uses, web_origin(ctx.request))
+ except mesh.MeshError as e:
+ raise ToolError(str(e)) from None
+ if made["turned_on"]:
+ auth.audit(ctx.db, ctx.user.as_audit(), "settings.save", "mesh", ["enabled", "mcp"])
+ tid = made["token"]["id"]
+ auth.audit(ctx.db, ctx.user.as_audit(), "mesh.token.create", f"mesh_token:{tid}", {"role": role, "uses": uses, "via": "mcp"})
+ return {k: made[k] for k in ("token", "secret", "join_url", "install_line", "turned_on")} | {
+ "note": "the install line and its token are shown this once: give them to the person, who runs the line on the machine",
+ "settings": f"{ctx.web}/settings/nodes",
+ }
+
+
+@tool(
+ "change_mesh_node",
+ "Change a machine on the mesh",
+ "Rename a machine on the mesh, or change the namespaces it serves (every_namespace: serve every one again); its "
+ "certificate follows when it next renews. Admins only, with a token that has the write scope.",
+ Arg("node_id", "integer", "the machine (from mesh)", required=True),
+ Arg("name", "string", "its new name", max_length=63),
+ Arg("namespaces", "string[]", "only the namespaces it serves from now on"),
+ Arg("every_namespace", "boolean", "serve every namespace again", default=False),
+ writes=True,
+ admin=True,
+)
+def change_mesh_node(
+ ctx: Context, node_id: int, name: str | None = None, namespaces: list[str] | None = None, every_namespace: bool = False
+) -> dict[str, Any]:
+ if every_namespace:
+ if namespaces:
+ raise ToolError("give namespaces or every_namespace, not both")
+ namespaces = []
+ if name is None and namespaces is None:
+ raise ToolError("say what to change: name, namespaces or every_namespace")
+ changes = {k: v for k, v in (("name", name), ("namespaces", namespaces)) if v is not None}
+ return {
+ "node": _mesh_do(
+ ctx, lambda: mesh.update(ctx.db, node_id, name=name, namespaces=namespaces), "mesh.node.change", f"mesh_node:{node_id}", changes
+ )
+ }
+
+
+@tool(
+ "remove_mesh_node",
+ "Take a machine off the mesh",
+ "Take a machine off the mesh: its certificates go on every machine's blocklist and its credentials stop working "
+ "(a worker's database user goes too). restore_mesh_node undoes it while its certificate is good. Admins only, "
+ "with a token that has the write scope.",
+ Arg("node_id", "integer", "the machine (from mesh)", required=True),
+ writes=True,
+ admin=True,
+)
+def remove_mesh_node(ctx: Context, node_id: int) -> dict[str, Any]:
+ return {"node": _mesh_do(ctx, lambda: mesh.remove(ctx.db, node_id, by=ctx.user.email), "mesh.node.remove", f"mesh_node:{node_id}")}
+
+
+@tool(
+ "restore_mesh_node",
+ "Bring a removed machine back",
+ "Undo taking a machine off the mesh, while its certificate is still good (after that it joins again with a new "
+ "token). Admins only, with a token that has the write scope.",
+ Arg("node_id", "integer", "the machine (from mesh)", required=True),
+ writes=True,
+ admin=True,
+)
+def restore_mesh_node(ctx: Context, node_id: int) -> dict[str, Any]:
+ return {"node": _mesh_do(ctx, lambda: mesh.undo_remove(ctx.db, node_id, ctx.cfg), "mesh.node.restore", f"mesh_node:{node_id}")}
+
+
+@tool(
+ "withdraw_mesh_token",
+ "Withdraw a join token",
+ "Withdraw a join token not used up yet (from mesh): no machine can join with it any more; those that did stay. "
+ "Admins only, with a token that has the write scope.",
+ Arg("token_id", "integer", "the token (from mesh)", required=True),
+ writes=True,
+ admin=True,
+)
+def withdraw_mesh_token(ctx: Context, token_id: int) -> dict[str, Any]:
+ _mesh_do(ctx, lambda: mesh.revoke_token(ctx.db, token_id) or {}, "mesh.token.withdraw", f"mesh_token:{token_id}")
+ return {"withdrawn": token_id, "tokens": mesh.tokens(ctx.db)}
+
+
# ---------- monitoring: Prometheus and Grafana next to Lens (admins) ----------
@tool(
"monitoring",
diff --git a/fastapi_backend/app/api/v1/routes/chats.py b/fastapi_backend/app/api/v1/routes/chats.py
index f76dadbef..d3efc37f9 100644
--- a/fastapi_backend/app/api/v1/routes/chats.py
+++ b/fastapi_backend/app/api/v1/routes/chats.py
@@ -38,6 +38,7 @@
chat_export,
convert,
llm,
+ ops_tools,
research,
sandbox,
store,
@@ -943,6 +944,6 @@ def decide_approval(aid: int, body: ApprovalDecision, user: Writer, acl: Acl, db
raise HTTPException(403, str(e)) from None
except (ValueError, KeyError) as e:
raise HTTPException(400, str(e)) from None
- auth.audit(db, user.as_audit(), "assistant.approval", f"approval:{aid}", {"decision": body.decision, **out})
+ auth.audit(db, user.as_audit(), "assistant.approval", f"approval:{aid}", {"decision": body.decision, **ops_tools.kept(out)})
request.app.state.graph_cache.clear() # an approved entity or topic change shows in the graph at once
return out
diff --git a/fastapi_backend/app/api/v1/routes/mesh.py b/fastapi_backend/app/api/v1/routes/mesh.py
index 7b7ce1a5f..bf0e5be62 100644
--- a/fastapi_backend/app/api/v1/routes/mesh.py
+++ b/fastapi_backend/app/api/v1/routes/mesh.py
@@ -16,7 +16,7 @@
from app.api.deps import AdminReader, AdminWriter, Cfg, Db, client_ip, domain_errors, web_origin
from app.api.v1.routes.jobs import _worker as worker_info
-from app.domain import auth, jobs, keyring, mesh, settings
+from app.domain import auth, jobs, keyring, mesh
from app.schemas.common import Ok
from app.schemas.mesh import (
MeshBeat,
@@ -108,18 +108,17 @@ def mesh_tokens(user: AdminReader, db: Db) -> list[MeshToken]:
def make_mesh_token(body: MeshTokenCreate, user: AdminWriter, request: Request, db: Db, cfg: Cfg) -> MeshTokenCreated:
"""Add a node: a token another machine joins the mesh with, shown this once. Makes the mesh's CA the first time,
and turns the mesh on."""
+ base, url = request.app.state.archive.base, web_origin(request)
with domain_errors():
try:
- tok, secret = mesh.make_token(db, cfg, user.email, body.role, body.name, body.namespaces, body.hours, body.uses)
+ made = mesh.add(db, cfg, base, user.email, body.role, body.name, body.namespaces, body.hours, body.uses, url)
except mesh.MeshError as e:
raise HTTPException(503, str(e)) from None
- if not mesh.conf(cfg)["enabled"]:
- settings.save(db, request.app.state.archive.base, "mesh", {"enabled": True}, user.email)
- auth.audit(db, user.as_audit(), "settings.save", "mesh", ["enabled"])
- auth.audit(db, user.as_audit(), "mesh.token.create", f"mesh_token:{tok['id']}", {"role": body.role, "uses": body.uses})
- url = web_origin(request)
+ if made["turned_on"]:
+ auth.audit(db, user.as_audit(), "settings.save", "mesh", ["enabled"])
+ auth.audit(db, user.as_audit(), "mesh.token.create", f"mesh_token:{made['token']['id']}", {"role": body.role, "uses": body.uses})
return MeshTokenCreated(
- token=MeshToken(**tok), secret=secret, join_url=url, install_line=mesh.join_line(cfg, secret, url, role=body.role)
+ token=MeshToken(**made["token"]), secret=made["secret"], join_url=made["join_url"], install_line=made["install_line"]
)
diff --git a/fastapi_backend/app/domain/ai_tools.py b/fastapi_backend/app/domain/ai_tools.py
index edf17dc6a..6deb6f8fc 100644
--- a/fastapi_backend/app/domain/ai_tools.py
+++ b/fastapi_backend/app/domain/ai_tools.py
@@ -638,6 +638,7 @@ def builtin_names():
"mark_activities",
"decline_approval",
"scaling",
+ "mesh",
"connections",
"lens_help",
} | {
@@ -2442,7 +2443,7 @@ def approve(db, cfg, aid, user, editable, decision="approve", base=None, admin=F
r=R("approval", a["id"]),
t=store.now(),
u=user["email"],
- res=result,
+ res=ops_tools.kept(result), # a new node's install line goes to the person who approved, once, and isn't kept
)
return {"status": "done", **result}
@@ -2482,6 +2483,7 @@ def _carry_out(db, cfg, a, user, editable, decision, base, admin, readable, via=
"subscribe_feed",
"unsubscribe_feed",
*ops_tools.scaling.TOOLS,
+ *ops_tools.MESH,
): # a scaling group's terms are approved only by a yes in the web app (via web)
result = ops_tools.apply(db, cfg, base or cfg, a["tool"], args, user, editable, admin, via)
elif a["tool"] == "decline_approval": # the person's yes to declining another of their approvals
diff --git a/fastapi_backend/app/domain/bridge.py b/fastapi_backend/app/domain/bridge.py
index 093fb0f2f..7d635a500 100644
--- a/fastapi_backend/app/domain/bridge.py
+++ b/fastapi_backend/app/domain/bridge.py
@@ -49,6 +49,7 @@
llm,
matterbridge,
ns_assistant,
+ ops_tools,
research,
store,
untrusted,
@@ -501,7 +502,13 @@ def decide_in_room(db, cfg, base, account, cid, m, q):
except (ValueError, PermissionError, KeyError) as e:
lines.append(f"Couldn't do “{a['summary']}”: {e}")
continue
- auth.audit(db, user, "assistant.approval", f"approval:{a['id']}", {"decision": decision, "via": "chat room", "by": who, **out})
+ auth.audit(
+ db,
+ user,
+ "assistant.approval",
+ f"approval:{a['id']}",
+ {"decision": decision, "via": "chat room", "by": who, **ops_tools.kept(out)},
+ )
if out.get("status") == "failed":
lines.append(f"Couldn't do “{a['summary']}”: {out.get('error')}")
continue
diff --git a/fastapi_backend/app/domain/mesh.py b/fastapi_backend/app/domain/mesh.py
index 6a9f0d5bb..3f6d71baf 100644
--- a/fastapi_backend/app/domain/mesh.py
+++ b/fastapi_backend/app/domain/mesh.py
@@ -519,9 +519,9 @@ def tokens(db):
return [_token_view(r) for r in rows if not r.get("revoked_at") and (r.get("used") or 0) < (r.get("uses") or 1)]
-def make_token(db, cfg, by=None, role="worker", name=None, namespaces=None, hours=24, uses=1):
- """A token another machine joins with: (token row, the token itself, shown this once). Makes the CA if there isn't
- one yet. The caller turns the mesh on (settings), which is what adding a node means."""
+def check_token(db, role="worker", name=None, namespaces=None, hours=24, uses=1):
+ """A join token's terms checked, before anything is made (the assistant says what's wrong before it asks): its
+ (name, namespaces) tidied. ValueError says what isn't right."""
if role not in ROLES:
raise ValueError(f"a node is a {' or a '.join(ROLES)}")
name = (name or "").strip() or None
@@ -540,6 +540,13 @@ def make_token(db, cfg, by=None, role="worker", name=None, namespaces=None, hour
"a worker on another machine needs this install's database to be a SurrealDB server (Docker installs have one); "
"add a compute node instead"
)
+ return name, namespaces
+
+
+def make_token(db, cfg, by=None, role="worker", name=None, namespaces=None, hours=24, uses=1):
+ """A token another machine joins with: (token row, the token itself, shown this once). Makes the CA if there isn't
+ one yet. The caller turns the mesh on (settings), which is what adding a node means."""
+ name, namespaces = check_token(db, role, name, namespaces, hours, uses)
ca(db, cfg)
primary(db, cfg)
tid, secret = db.next_id("mesh_token"), secrets.token_urlsafe(32)
@@ -579,6 +586,21 @@ def join_line(cfg, token, url=None, role=None):
return f"curl -fsSL https://raw.githubusercontent.com/{repo}/main/install.sh | LENS_JOIN={url} LENS_JOIN_TOKEN={token}{extra} sh"
+def add(db, cfg, base, by, role="worker", name=None, namespaces=None, hours=24, uses=1, url=None):
+ """Add a node, as Settings › Nodes, MCP's add_mesh_node and the assistant's do: a join token and the line to run
+ on the machine (at `url`, else FRONTEND_URL), both shown this once, and the mesh turned on (mesh.enabled, saved
+ over `base` as `by`) when it's off. {token, secret, join_url, install_line, turned_on}; the caller audits."""
+ from app.config import settings as env
+
+ tok, secret = make_token(db, cfg, by, role, name, namespaces, hours, uses)
+ url = (url or env.FRONTEND_URL).rstrip("/")
+ line = join_line(cfg, secret, url, role=role)
+ turned_on = not conf(cfg)["enabled"]
+ if turned_on:
+ settings.save(db, base, "mesh", {"enabled": True}, by)
+ return {"token": tok, "secret": secret, "join_url": url, "install_line": line, "turned_on": turned_on}
+
+
def revoke_token(db, tid):
if not db.one("SELECT id FROM $r", r=R("mesh_token", int(tid))):
raise KeyError(tid)
@@ -951,6 +973,62 @@ def undo_remove(db, nid, cfg):
return node(db, nid)
+# ---------- agents: MCP's and the assistant's `mesh` ----------
+OFFLINE_AFTER = 180 # seconds: a node reports every minute, so one not heard from for three is offline (as on the Nodes page)
+
+
+def _online(last_seen, now):
+ try:
+ seen = dt.datetime.fromisoformat(str(last_seen).replace("Z", "+00:00"))
+ except ValueError:
+ return False
+ if seen.tzinfo is None:
+ seen = seen.replace(tzinfo=dt.timezone.utc)
+ return (now - seen).total_seconds() < OFFLINE_AFTER
+
+
+def agent_view(db, cfg):
+ """The mesh as an agent reads it: on or off, its CA, this machine's address on it, every machine with how it's
+ doing (the primary's Nebula is the `mesh` container's), and the join tokens not used yet, never their secrets."""
+ from . import updates
+
+ c, row, now = conf(cfg), ca_row(db), _now()
+ machines = []
+ for n in nodes(db):
+ s = n["status"] or {}
+ if n["role"] == "primary":
+ svc = service_view(db, cfg)
+ s = {"nebula": svc["state"], "version": updates.current(), "error": svc["error"]}
+ machines.append(
+ {
+ "id": n["id"],
+ "name": n["name"],
+ "role": n["role"],
+ "ip": n["ip"],
+ "online": n["role"] == "primary" or (bool(n["last_seen"]) and _online(n["last_seen"], now)),
+ "last_seen": n["last_seen"],
+ "nebula": s.get("nebula"),
+ "lens_version": s.get("version"),
+ "machine": s.get("machine") or s.get("info"),
+ "namespaces": n["namespaces"],
+ "certificate_until": n["not_after"],
+ # a compute node's sandbox gateway answers (docs/mesh.md, Compute nodes)
+ "sandbox_gateway": bool((s.get("sandbox") or {}).get("gateway")) if n["role"] == "compute" else None,
+ "error": str(s["error"])[:300] if s.get("error") else None,
+ "removed": n["revoked_at"],
+ "removed_by": n["revoked_by"],
+ }
+ )
+ return {
+ "enabled": c["enabled"],
+ "network": c["network"],
+ "primary_ip": primary_ip(cfg),
+ "ca": {"fingerprint": row["fingerprint"], "not_after": row["not_after"]} if row else None,
+ "nodes": machines,
+ "tokens": tokens(db),
+ }
+
+
# ---------- Nebula on this machine: the `mesh` container ----------
# Lens's server can't hold NET_ADMIN, so the primary's Nebula runs in the optional `mesh` container (mesh/sidecar.py),
# which shares a folder with it (LENS_MESH_DIR): Lens writes lens.json there (on or off, the config, the public key it
diff --git a/fastapi_backend/app/domain/ops_tools.py b/fastapi_backend/app/domain/ops_tools.py
index c6bb44b76..ea268252b 100644
--- a/fastapi_backend/app/domain/ops_tools.py
+++ b/fastapi_backend/app/domain/ops_tools.py
@@ -21,6 +21,7 @@
jobs,
links,
llm,
+ mesh,
metadata,
roles,
rss,
@@ -75,9 +76,23 @@
# where new files go; secrets is where Lens signs in to a password manager; scaling turns on what can launch paid
# machines
ALWAYS_ASK = {"telemetry", "analytics", "sensors", "shares", "files", "web", "secrets", "scaling"}
-ASK_TOOLS = {"invite_person", "change_person"} # who gets in always waits for the admin's approval
-# within a scaling group's approved terms (its min, max and budget), so made at once unless the answer read outside text
-WITHIN_BOUNDS = {"set_scaling_desired", "pause_scaling_group", "terminate_scaling_unit"}
+# who gets in always waits for the admin's approval: a person, or a machine joining the mesh; and so does taking a
+# machine off it, which stops what runs there
+ASK_TOOLS = {"invite_person", "change_person", "add_mesh_node", "remove_mesh_node"}
+# within a scaling group's approved terms (its min, max and budget), or a change to the mesh that's undone as easily
+# (renaming a node, the namespaces it serves, bringing a removed one back, withdrawing a token), so made at once
+# unless the answer read outside text
+WITHIN_BOUNDS = {
+ "set_scaling_desired",
+ "pause_scaling_group",
+ "terminate_scaling_unit",
+ "change_mesh_node",
+ "restore_mesh_node",
+ "withdraw_mesh_token",
+}
+# what a change's result shows the person who approved it once and never keeps (in the approval or the audit log):
+# a new node's install line, which holds its join token
+SHOWN_ONCE = ("install_line",)
_GROUP = {
"type": "object",
"description": "name, provider (its id), template (what each unit is, as the provider's driver asks), min, max, "
@@ -135,6 +150,74 @@
),
]
+_NAMESPACES = {"type": "array", "items": _S, "description": "the namespaces it serves (empty: every one)"}
+MESH_TOOLS = [
+ (
+ "mesh",
+ "Lens's private network between the machines it runs on (Settings › Nodes and Network): whether it's on, its "
+ "CA's fingerprint and expiry, this machine's address on it, every machine (id, name, role worker or compute, "
+ "address, online and last seen, Nebula, its Lens version and machine, the namespaces it serves, whether a "
+ "compute node's sandbox gateway runs, its error, when it was removed) and the join tokens not used yet.",
+ {},
+ [],
+ False,
+ ),
+ (
+ "add_mesh_node",
+ "Let another machine join the mesh: makes a join token and the line to run on that machine, which the person "
+ "sees once they approve (you don't). role worker runs jobs against this install's database; compute runs your "
+ "code in sandboxes and gets nothing of Lens's. Turns the mesh on when it's off.",
+ {
+ "role": {"type": "string", "enum": list(mesh.ROLES)},
+ "name": {"type": "string", "description": "the name it shows as (none: the name the machine sends)"},
+ "namespaces": _NAMESPACES,
+ "hours": {
+ "type": "integer",
+ "minimum": mesh.TOKEN_HOURS[0],
+ "maximum": mesh.TOKEN_HOURS[1],
+ "description": "how long the token works (24)",
+ },
+ "uses": {
+ "type": "integer",
+ "minimum": mesh.TOKEN_USES[0],
+ "maximum": mesh.TOKEN_USES[1],
+ "description": "machines that may join with it (1)",
+ },
+ },
+ [],
+ True,
+ ),
+ (
+ "change_mesh_node",
+ "Rename a machine on the mesh (its id from mesh), or change the namespaces it serves (empty: every one).",
+ {"node_id": {"type": "integer"}, "name": _S, "namespaces": _NAMESPACES},
+ ["node_id"],
+ True,
+ ),
+ (
+ "remove_mesh_node",
+ "Take a machine off the mesh (its id from mesh): its certificates are blocked on every machine and its "
+ "credentials stop working. restore_mesh_node brings it back while its certificate is good.",
+ {"node_id": {"type": "integer"}},
+ ["node_id"],
+ True,
+ ),
+ (
+ "restore_mesh_node",
+ "Bring back a machine taken off the mesh (its id from mesh), while its certificate is still good.",
+ {"node_id": {"type": "integer"}},
+ ["node_id"],
+ True,
+ ),
+ (
+ "withdraw_mesh_token",
+ "Withdraw a join token not used up yet (its id from mesh): no machine can join with it any more.",
+ {"token_id": {"type": "integer"}},
+ ["token_id"],
+ True,
+ ),
+]
+
ADMIN_TOOLS = [
(
"server_status",
@@ -259,7 +342,7 @@
True,
),
]
-ADMIN_TOOLS += SCALING_TOOLS
+ADMIN_TOOLS += SCALING_TOOLS + MESH_TOOLS
FILE_TOOLS = [
(
@@ -348,6 +431,10 @@ def apply(db, cfg, base, tool, args, user, editable, admin, via="agent"):
table = "scale_group" if "group" in out else "scale_node"
auth.audit(db, user, f"scaling.{tool}", f"{table}:{what.get('id')}", {"via": via, "assistant": True})
return out
+ if tool in MESH:
+ if not admin:
+ raise PermissionError("only admins manage the mesh")
+ return _mesh(db, cfg, base, tool, args, user)
if tool == "change_settings":
if not admin:
raise PermissionError("only admins change settings")
@@ -417,6 +504,46 @@ def apply(db, cfg, base, tool, args, user, editable, admin, via="agent"):
raise ValueError(f"no tool {tool}")
+MESH = {t[0] for t in MESH_TOOLS if t[4]}
+
+
+def kept(result):
+ """A change's result as it's kept (in its approval and the audit log): without what's shown only once."""
+ return {k: v for k, v in result.items() if k not in SHOWN_ONCE}
+
+
+def _mesh(db, cfg, base, tool, args, user):
+ """A change to the mesh (approved, or one made at once), audited as the web app's are."""
+ by, nid = user["email"], args.get("node_id")
+ try:
+ if tool == "add_mesh_node":
+ role = args.get("role") or "worker"
+ terms = {k: args[k] for k in ("name", "namespaces", "hours", "uses") if args.get(k) is not None}
+ made = mesh.add(db, cfg, base, by, role, url=args.get("url"), **terms)
+ if made["turned_on"]:
+ auth.audit(db, user, "settings.save", "mesh", ["enabled", "assistant"])
+ tid = made["token"]["id"]
+ auth.audit(db, user, "mesh.token.create", f"mesh_token:{tid}", {"role": role, "uses": made["token"]["uses"], "assistant": True})
+ return {"token": made["token"], "install_line": made["install_line"], "turned_on": made["turned_on"]}
+ if tool == "change_mesh_node":
+ changes = {k: args[k] for k in ("name", "namespaces") if args.get(k) is not None}
+ node = mesh.update(db, nid, **changes)
+ auth.audit(db, user, "mesh.node.change", f"mesh_node:{nid}", {**changes, "assistant": True})
+ elif tool == "remove_mesh_node":
+ node = mesh.remove(db, nid, by=by)
+ auth.audit(db, user, "mesh.node.remove", f"mesh_node:{nid}", ["assistant"])
+ elif tool == "restore_mesh_node":
+ node = mesh.undo_remove(db, nid, cfg)
+ auth.audit(db, user, "mesh.node.restore", f"mesh_node:{nid}", ["assistant"])
+ else:
+ mesh.revoke_token(db, args["token_id"])
+ auth.audit(db, user, "mesh.token.withdraw", f"mesh_token:{args['token_id']}", ["assistant"])
+ return {"withdrawn": args["token_id"]}
+ except mesh.MeshError as e:
+ raise ValueError(str(e)) from None
+ return {"node": {k: node[k] for k in ("id", "name", "role", "ip", "namespaces", "revoked_at")}}
+
+
def people(db):
"""Everyone with an account, for the assistant."""
names = store.space_names(db)
@@ -589,6 +716,62 @@ def t_terminate_scaling_unit(self, unit_id, why=None):
args = store.clean({"unit_id": n["id"], "why": why})
return self._change("terminate_scaling_unit", args, f"Let the unit {n['name']} go")
+ def t_mesh(self):
+ v = mesh.agent_view(self.db, self.cfg)
+ if not v["enabled"]:
+ v["note"] = "the mesh is off: add_mesh_node turns it on with the first node"
+ on = sum(n["online"] and n["role"] != "primary" and not n["removed"] for n in v["nodes"])
+ return v, f"Read the mesh: {on} machine{'' if on == 1 else 's'} online besides this one"
+
+ def _mesh_node(self, node_id):
+ try:
+ n = mesh.node(self.db, int(node_id))
+ except (KeyError, TypeError, ValueError):
+ raise ValueError("there's no machine on the mesh with that id: mesh lists them") from None
+ return n
+
+ def t_add_mesh_node(self, role="worker", name=None, namespaces=None, hours=24, uses=1):
+ from app.email import app_url
+
+ role, hours, uses = role or "worker", 24 if hours is None else hours, 1 if uses is None else uses
+ name, namespaces = mesh.check_token(self.db, role, name, namespaces, hours, uses) # said now, not once approved
+ what = f" named {name}" if name else ""
+ serves = f", serving {', '.join(namespaces)}" if namespaces else ""
+ times = "once" if uses == 1 else f"{uses} times"
+ on = "" if mesh.conf(self.cfg)["enabled"] else ", and turn the mesh on"
+ summary = f"Let a new {role} node{what} join the mesh{serves}: a join token that works {times}, for {hours} hours{on}"
+ url = (getattr(self, "web_app", None) or app_url(self.cfg, self.db)).rstrip("/") # where the machine joins
+ args = store.clean({"role": role, "name": name, "namespaces": namespaces or None, "hours": hours, "uses": uses, "url": url})
+ return self._change("add_mesh_node", args, summary)
+
+ def t_change_mesh_node(self, node_id, name=None, namespaces=None):
+ n = self._mesh_node(node_id)
+ if name is None and namespaces is None:
+ raise ValueError("say what to change: name or namespaces")
+ parts = [f"rename it {name.strip()}"] if name is not None else []
+ if namespaces is not None:
+ parts.append(f"serve {', '.join(sorted(set(namespaces)))}" if namespaces else "serve every namespace")
+ args = store.clean({"node_id": n["id"], "name": name, "namespaces": None if namespaces is None else list(namespaces)})
+ return self._change("change_mesh_node", args, f"{n['name']} on the mesh: {', '.join(parts)}")
+
+ def t_remove_mesh_node(self, node_id):
+ n = self._mesh_node(node_id)
+ if n["role"] == "primary":
+ raise ValueError("that's this machine, the mesh's primary: the mesh is turned off in Settings › Network")
+ if n["revoked_at"]:
+ raise ValueError(f"{n['name']} is already off the mesh")
+ return self._change("remove_mesh_node", {"node_id": n["id"]}, f"Take {n['name']} ({n['role']}, {n['ip']}) off the mesh")
+
+ def t_restore_mesh_node(self, node_id):
+ n = self._mesh_node(node_id)
+ return self._change("restore_mesh_node", {"node_id": n["id"]}, f"Bring {n['name']} back onto the mesh")
+
+ def t_withdraw_mesh_token(self, token_id):
+ t = next((t for t in mesh.tokens(self.db) if str(t["id"]) == str(token_id)), None)
+ if not t:
+ raise ValueError("there's no join token not used up with that id: mesh lists them")
+ return self._change("withdraw_mesh_token", {"token_id": t["id"]}, f"Withdraw the {t['role']} join token #{t['id']}")
+
def t_server_status(self):
return status(self.db, self.cfg, self.base), "Checked what's set up"
diff --git a/fastapi_backend/app/schemas/chats.py b/fastapi_backend/app/schemas/chats.py
index a722cc137..87aeba811 100644
--- a/fastapi_backend/app/schemas/chats.py
+++ b/fastapi_backend/app/schemas/chats.py
@@ -515,3 +515,6 @@ class ApprovalOutcome(ResponseModel):
error: str | None = Field(default=None, description="why an automation's action failed")
result: Any = Field(default=None, description="what an automation's action gave back")
always: bool | None = Field(default=None, description="that node runs without asking from now on")
+ install_line: str | None = Field(
+ default=None, description="the line to run on the new machine, for add_mesh_node: shown this once and not kept"
+ )
diff --git a/fastapi_backend/tests/api/test_approvals.py b/fastapi_backend/tests/api/test_approvals.py
index 51801f156..e3cc89ce2 100644
--- a/fastapi_backend/tests/api/test_approvals.py
+++ b/fastapi_backend/tests/api/test_approvals.py
@@ -169,7 +169,15 @@ def test_approve_carries_the_action_out_and_the_run_records_it(app, client, db,
# one that fails is failed, said on the run, and not tried again
bad = approvals.ask(db, cfg, intent(people, n=8, params={"text": "boom"}))
out = client.post(f"/api/v1/approvals/{bad}", headers=h, json={"decision": "approve"}).json()
- assert out == {"status": "failed", "error": "the room is gone", "batch": None, "job": None, "result": None, "always": None}
+ assert out == {
+ "status": "failed",
+ "error": "the room is gone",
+ "batch": None,
+ "job": None,
+ "result": None,
+ "always": None,
+ "install_line": None,
+ }
assert studio["intents"][-1] == (51, "51-n8", "failed", {"error": "the room is gone"})
diff --git a/fastapi_backend/tests/api/test_mcp.py b/fastapi_backend/tests/api/test_mcp.py
index edc6e125f..3e22190a9 100644
--- a/fastapi_backend/tests/api/test_mcp.py
+++ b/fastapi_backend/tests/api/test_mcp.py
@@ -105,6 +105,11 @@ def test_clients_are_sent_to_sign_in(client, app, env):
"set_scaling_desired",
"pause_scaling_group",
"terminate_scaling_unit",
+ "add_mesh_node",
+ "change_mesh_node",
+ "remove_mesh_node",
+ "restore_mesh_node",
+ "withdraw_mesh_token",
"set_monitoring",
"set_service",
"set_sandbox_gateway",
diff --git a/fastapi_backend/tests/api/test_mesh_agents.py b/fastapi_backend/tests/api/test_mesh_agents.py
new file mode 100644
index 000000000..5bbf50a93
--- /dev/null
+++ b/fastapi_backend/tests/api/test_mesh_agents.py
@@ -0,0 +1,224 @@
+"""The mesh through agents (docs/mesh.md, "Agents"): an admin's agent reads it, adds machines and changes them, over
+MCP and in the assistant. Over MCP a change needs an admin's write-scope token and is made at once, audited; in the
+assistant adding a machine and taking one off always wait for the person's yes, while renaming one, bringing one back
+and withdrawing a join token happen at once. A join token's secret is never in what the read tools say, and an
+approved install line goes to the person once and isn't kept."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from app.domain import mesh, settings, store
+from tests import fake_llm
+from tests.api._assist import Assist, sse, start_llm
+from tests.api.test_mcp import rpc, tool, tool_error
+from tests.api.test_mesh import joined, nebula, server_db # noqa: F401 - the fake nebula-cert, a database server
+from tests.api.test_oauth import _bearer, _grant
+from tests.helpers import login, make_user
+
+
+@pytest.fixture
+def llm(cfg):
+ srv = start_llm(cfg)
+ yield fake_llm.Handler
+ srv.shutdown()
+
+
+@pytest.fixture
+def app(cfg, db, llm):
+ from app.main import create_app
+
+ return create_app(cfg, db, background=False)
+
+
+def call(i, name, args):
+ return {"id": f"c{i}", "type": "function", "function": {"name": name, "arguments": json.dumps(args)}}
+
+
+def named(client, h, t, **args):
+ """tool(), for a tool that takes a `name`."""
+ res = rpc(client, h, "tools/call", {"name": t, "arguments": args})["result"]
+ assert res["isError"] is False, res
+ return res["structuredContent"]
+
+
+def audited(db):
+ return db.rows("SELECT at, action, target, detail FROM audit_log ORDER BY at")
+
+
+def test_mcp_clients_add_and_manage_mesh_nodes(client, db, cfg, nebula, server_db): # noqa: F811
+ make_user(db, "root@x.io", "root password 1", admin=True)
+ h = login(client, "root@x.io", "root password 1")
+ m = _bearer(_grant(client, h, scope="read write")[1])
+ ro = _bearer(_grant(client, h, scope="read")[1])
+ assert tool(client, m, "mesh")["enabled"] is False
+ assert "read-only" in tool_error(client, ro, "add_mesh_node")
+ assert mesh.tokens(db) == []
+
+ made = named(client, m, "add_mesh_node", name="studio", hours=2)
+ secret = made["secret"]
+ assert made["install_line"].endswith(f"LENS_JOIN={made['join_url']} LENS_JOIN_TOKEN={secret} sh")
+ assert made["join_url"].startswith("http") and made["turned_on"] is True and made["token"]["role"] == "worker"
+ assert settings.effective(db, cfg)["mesh"]["enabled"] is True # adding the first node turned the mesh on
+ rows = audited(db)
+ assert ("mesh.token.create", f"mesh_token:{made['token']['id']}") in [(r["action"], r["target"]) for r in rows]
+ assert {"role": "worker", "uses": 1, "via": "mcp"} in [r["detail"] for r in rows]
+ assert ["enabled", "mcp"] in [r["detail"] for r in rows if r["action"] == "settings.save"]
+ assert secret.split(".")[-1] not in json.dumps(rows, default=str)
+ assert "at least 1" in tool_error(client, m, "add_mesh_node", hours=0)
+
+ nid, answer, _ = joined(client, cfg, secret)
+ nh = {"Authorization": f"Bearer {answer['node_token']}"}
+ beat = {"nebula": "running", "version": "9.9.9", "machine": {"os": "linux", "cpus": 8}, "error": "fine"}
+ assert client.post("/api/v1/mesh/node/beat", json=beat, headers=nh).status_code == 200
+ seen = tool(client, ro, "mesh") # a read-only token reads it
+ assert seen["enabled"] is True and seen["primary_ip"] == "10.73.0.1" and seen["ca"]["fingerprint"]
+ assert seen["settings"].endswith("/settings/nodes")
+ primary, node = seen["nodes"]
+ assert primary["role"] == "primary" and primary["online"] is True
+ assert {k: node[k] for k in ("id", "name", "role", "ip", "online", "nebula", "lens_version", "error", "removed")} == {
+ "id": nid,
+ "name": "studio",
+ "role": "worker",
+ "ip": "10.73.0.2",
+ "online": True,
+ "nebula": "running",
+ "lens_version": "9.9.9",
+ "error": "fine",
+ "removed": None,
+ }
+ assert node["machine"]["cpus"] == 8 and node["sandbox_gateway"] is None # a worker runs no sandboxes
+
+ # change, take off, bring back: at once, audited
+ assert "read-only" in tool_error(client, ro, "remove_mesh_node", node_id=nid)
+ out = named(client, m, "change_mesh_node", node_id=nid, name="Studio Mac", namespaces=["calls"])
+ assert out["node"]["name"] == "Studio Mac" and out["node"]["groups"] == ["lens-node", "lens-worker", "ns-calls"]
+ assert tool(client, m, "change_mesh_node", node_id=nid, every_namespace=True)["node"]["namespaces"] == []
+ assert "say what to change" in tool_error(client, m, "change_mesh_node", node_id=nid)
+ assert "no namespace" in tool_error(client, m, "change_mesh_node", node_id=nid, namespaces=["nope"])
+ gone = tool(client, m, "remove_mesh_node", node_id=nid)["node"]
+ assert gone["revoked_at"] and gone["revoked_by"] == "root@x.io"
+ assert client.get("/api/v1/mesh/node/config", headers=nh).status_code == 401
+ assert tool(client, m, "mesh")["nodes"][1]["removed"] == gone["revoked_at"]
+ assert tool(client, m, "restore_mesh_node", node_id=nid)["node"]["revoked_at"] is None
+ assert "primary" in tool_error(client, m, "remove_mesh_node", node_id=primary["id"])
+ assert "not found" in tool_error(client, m, "remove_mesh_node", node_id=999)
+
+ # a token not used yet is listed without its secret, and withdrawn
+ other = tool(client, m, "add_mesh_node", role="compute", uses=3)
+ assert other["install_line"].endswith(" LENS_NODE_SANDBOX=1 sh") and other["turned_on"] is False
+ listed = tool(client, m, "mesh")["tokens"]
+ assert [t["id"] for t in listed] == [other["token"]["id"]] and listed[0]["uses"] == 3
+ assert other["secret"].split(".")[-1] not in json.dumps(listed)
+ assert tool(client, m, "withdraw_mesh_token", token_id=other["token"]["id"])["tokens"] == []
+ actions = [r["action"] for r in audited(db)]
+ for a in ("mesh.node.change", "mesh.node.remove", "mesh.node.restore", "mesh.token.withdraw"):
+ assert a in actions
+
+ make_user(db, "ed@x.io", "editor password 1", roles={"pods": "editor"})
+ ed = _bearer(_grant(client, login(client, "ed@x.io", "editor password 1"), scope="read write")[1])
+ assert "only admins" in tool_error(client, ed, "mesh")
+ assert "only admins" in tool_error(client, ed, "add_mesh_node")
+ assert "only admins" in tool_error(client, ed, "restore_mesh_node", node_id=nid)
+
+
+def test_the_assistant_adds_and_removes_machines_once_the_person_approves(app, db, cfg, folder, new_client, llm, nebula, server_db): # noqa: F811
+ s = Assist(app, db, cfg, folder, new_client)
+ c, h = s.cl["admin"]
+ llm.tool_script = [
+ {"content": "", "tool_calls": [call(1, "add_mesh_node", {"role": "worker", "name": "studio", "namespaces": ["pods"]})]},
+ {"content": "Approve it, then run the line on the Mac."},
+ ]
+ cid = c.post("/api/v1/chats", headers=h, json={}).json()["id"]
+ ev = sse(c.post(f"/api/v1/chats/{cid}/messages", headers=h, json={"content": "add my Mac as a worker"}).text)
+ (appr,) = ev["approval"]
+ assert appr["summary"] == (
+ "Let a new worker node named studio join the mesh, serving pods: a join token that works once, for 24 hours, and turn the mesh on"
+ )
+ assert mesh.tokens(db) == [] and settings.effective(db, cfg)["mesh"]["enabled"] is False # nothing yet
+
+ out = c.post(f"/api/v1/approvals/{appr['id']}", headers=h, json={"decision": "approve"}).json()
+ assert out["status"] == "done" and out["token"]["namespaces"] == ["pods"] and out["turned_on"] is True
+ line = out["install_line"]
+ secret = line.split("LENS_JOIN_TOKEN=")[1].split()[0]
+ assert secret.startswith(mesh.TOKEN_PREFIX) and "LENS_JOIN=http" in line
+ assert settings.effective(db, cfg)["mesh"]["enabled"] is True
+ # the line went to the person, once: not kept in the approval, its audit, or anything the model was sent
+ kept = db.one("SELECT result FROM $r", r=store.R("approval", appr["id"]))["result"]
+ assert kept["token"]["id"] == out["token"]["id"] and "install_line" not in kept
+ assert secret.split(".")[-1] not in json.dumps(audited(db), default=str)
+ assert c.get(f"/api/v1/approvals/{appr['id']}", headers=h).json()["result"] == kept
+ assert "mesh.token.create" in [r["action"] for r in audited(db)]
+
+ nid, _answer, _ = joined(c, cfg, secret)
+ llm.tool_script = [
+ {"content": "", "tool_calls": [call(2, "mesh", {})]},
+ {"content": "", "tool_calls": [call(3, "remove_mesh_node", {"node_id": nid})]},
+ {"content": "Approve it to take the Mac off."},
+ ]
+ ev = sse(c.post(f"/api/v1/chats/{cid}/messages", headers=h, json={"content": "take the Mac off"}).text)
+ sent = json.dumps(llm.seen)
+ assert '"name": "studio"' in sent.replace('\\"', '"') and secret.split(".")[-1] not in sent # it read the mesh, never the secret
+ (appr,) = ev["approval"]
+ assert appr["summary"] == "Take studio (worker, 10.73.0.2) off the mesh"
+ assert mesh.node(db, nid)["revoked_at"] is None
+ out = c.post(f"/api/v1/approvals/{appr['id']}", headers=h, json={"decision": "approve"}).json()
+ assert out["status"] == "done" and out["node"]["revoked_at"]
+ assert mesh.node(db, nid)["revoked_by"] == "root@x.io"
+ assert ("mesh.node.remove", ["assistant"]) in [(r["action"], r["detail"]) for r in audited(db)]
+
+
+def test_the_assistant_renames_restores_and_withdraws_at_once(app, db, cfg, folder, new_client, llm, nebula, server_db): # noqa: F811
+ s = Assist(app, db, cfg, folder, new_client)
+ c, h = s.cl["admin"]
+ made = mesh.add(db, cfg, cfg, "root@x.io")
+ nid, _answer, _ = joined(c, cfg, made["secret"])
+ mesh.remove(db, nid, by="root@x.io")
+ spare, _secret = mesh.make_token(db, cfg, "root@x.io", "compute")
+ llm.tool_script = [
+ {"content": "", "tool_calls": [call(0, "mesh", {})]}, # Lens's own word: what follows still happens at once
+ {"content": "", "tool_calls": [call(1, "restore_mesh_node", {"node_id": nid})]},
+ {"content": "", "tool_calls": [call(2, "change_mesh_node", {"node_id": nid, "name": "Studio Mac", "namespaces": ["calls"]})]},
+ {"content": "", "tool_calls": [call(3, "withdraw_mesh_token", {"token_id": spare["id"]})]},
+ {"content": "Done."},
+ ]
+ cid = c.post("/api/v1/chats", headers=h, json={}).json()["id"]
+ ev = sse(c.post(f"/api/v1/chats/{cid}/messages", headers=h, json={"content": "bring the Mac back for calls"}).text)
+ assert not ev.get("approval")
+ n = mesh.node(db, nid)
+ assert n["revoked_at"] is None and n["name"] == "Studio Mac" and n["namespaces"] == ["calls"]
+ assert mesh.tokens(db) == []
+ details = {r["action"]: r["detail"] for r in audited(db)}
+ assert details["mesh.node.restore"] == ["assistant"] and details["mesh.token.withdraw"] == ["assistant"]
+ assert details["mesh.node.change"] == {"name": "Studio Mac", "namespaces": ["calls"], "assistant": True}
+
+
+def test_a_setup_conversation_still_asks_before_a_machine_joins_or_goes(app, db, cfg, folder, new_client, llm, nebula, server_db): # noqa: F811
+ s = Assist(app, db, cfg, folder, new_client)
+ c, h = s.cl["admin"]
+ made = mesh.add(db, cfg, cfg, "root@x.io")
+ nid, _answer, _ = joined(c, cfg, made["secret"])
+ llm.tool_script = [
+ {"content": "", "tool_calls": [call(1, "add_mesh_node", {"role": "compute"})]},
+ {"content": "", "tool_calls": [call(2, "remove_mesh_node", {"node_id": nid})]},
+ {"content": "Both wait for you."},
+ ]
+ cid = c.post("/api/v1/chats", headers=h, json={"kind": "setup"}).json()["id"]
+ ev = sse(c.post(f"/api/v1/chats/{cid}/messages", headers=h, json={"content": "set up the nodes"}).text)
+ assert [a["summary"] for a in ev["approval"]] == [
+ "Let a new compute node join the mesh: a join token that works once, for 24 hours",
+ "Take studio (worker, 10.73.0.2) off the mesh",
+ ]
+ assert mesh.tokens(db) == [] and mesh.node(db, nid)["revoked_at"] is None
+
+
+def test_only_admins_get_the_mesh_tools(app, db, cfg, folder, new_client, llm):
+ s = Assist(app, db, cfg, folder, new_client)
+ c, h = s.cl["editor"]
+ llm.tool_script = [{"content": "Hi."}]
+ cid = c.post("/api/v1/chats", headers=h, json={}).json()["id"]
+ sse(c.post(f"/api/v1/chats/{cid}/messages", headers=h, json={"content": "hi"}).text)
+ offered = {t["function"]["name"] for t in llm.seen[-1].get("tools") or []}
+ assert not offered & {"mesh", "add_mesh_node", "change_mesh_node", "remove_mesh_node", "restore_mesh_node", "withdraw_mesh_token"}
diff --git a/nextjs-frontend/__tests__/approval-install-line.test.tsx b/nextjs-frontend/__tests__/approval-install-line.test.tsx
new file mode 100644
index 000000000..8e861421a
--- /dev/null
+++ b/nextjs-frontend/__tests__/approval-install-line.test.tsx
@@ -0,0 +1,70 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import "@testing-library/jest-dom";
+import type { ReactNode } from "react";
+
+import { Chats } from "@/app/openapi-client";
+import { ApprovalCard } from "@/components/chat/approval";
+import { TooltipProvider } from "@/components/ui/tooltip";
+
+jest.mock("@/app/openapi-client", () => ({ Chats: { decideApproval: jest.fn() } }));
+jest.mock("next-auth/react", () => ({ useSession: () => ({ data: { accessToken: "t" } }) }));
+
+const LINE =
+ "curl -fsSL https://raw.githubusercontent.com/adeelahmad/lense/main/install.sh | LENS_JOIN=http://lens.local LENS_JOIN_TOKEN=lensjoin1.4.abc sh";
+
+function wrap(ui: ReactNode) {
+ const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+ return render(
+
+ {ui}
+ ,
+ );
+}
+
+describe("approving a new mesh node", () => {
+ it("shows its install line this once, until the person is done with it", async () => {
+ (Chats.decideApproval as jest.Mock).mockResolvedValue({
+ data: { status: "done", install_line: LINE, token: { id: 4 } },
+ response: { ok: true, status: 200 },
+ });
+ const decided = jest.fn();
+ wrap(
+ ,
+ );
+ fireEvent.click(screen.getByRole("button", { name: "Approve" }));
+ expect(await screen.findByText(LINE)).toBeInTheDocument();
+ expect(screen.getByRole("button", { name: "Copy the install line" })).toBeInTheDocument();
+ expect(screen.getByText(/The line isn’t shown again/)).toBeInTheDocument();
+ expect(decided).not.toHaveBeenCalled(); // the inbox would read the list again and take the card, line and all, away
+ fireEvent.click(screen.getByRole("button", { name: "Done" }));
+ await waitFor(() => expect(decided).toHaveBeenCalledTimes(1));
+ });
+
+ it("says nothing more for an approval without one", async () => {
+ (Chats.decideApproval as jest.Mock).mockResolvedValue({
+ data: { status: "done" },
+ response: { ok: true, status: 200 },
+ });
+ const decided = jest.fn();
+ wrap(
+ ,
+ );
+ fireEvent.click(screen.getByRole("button", { name: "Approve" }));
+ expect(await screen.findByText("Approved: Take studio off the mesh")).toBeInTheDocument();
+ await waitFor(() => expect(decided).toHaveBeenCalledTimes(1));
+ expect(screen.queryByRole("button", { name: "Done" })).not.toBeInTheDocument();
+ });
+});
diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts
index 1ea4d4d88..b25f22e07 100644
--- a/nextjs-frontend/app/openapi-client/types.gen.ts
+++ b/nextjs-frontend/app/openapi-client/types.gen.ts
@@ -1222,6 +1222,12 @@ export type ApprovalOutcome = {
* that node runs without asking from now on
*/
always?: boolean | null;
+ /**
+ * Install Line
+ *
+ * the line to run on the new machine, for add_mesh_node: shown this once and not kept
+ */
+ install_line?: string | null;
[key: string]: unknown;
};
diff --git a/nextjs-frontend/components/chat/approval.tsx b/nextjs-frontend/components/chat/approval.tsx
index ea915c387..cd11b4c7e 100644
--- a/nextjs-frontend/components/chat/approval.tsx
+++ b/nextjs-frontend/components/chat/approval.tsx
@@ -8,6 +8,7 @@ import type { ApprovalOutcome, Estimate } from "@/app/openapi-client/types.gen";
import { approxCount, money } from "@/components/batches/format";
import { hoursShort } from "@/components/chat/scope";
import { Button } from "@/components/ui/button";
+import { CodeBlock } from "@/components/ui/states";
import { data, useApiClient } from "@/lib/api/browser";
import { plural } from "@/lib/format";
@@ -49,10 +50,11 @@ function Diamond({ size = 22 }: { size?: number }) {
);
}
-function Outcome({ a, outcome }: { a: ApprovalView; outcome: ApprovalOutcome | null }) {
+function Outcome({ a, outcome, onDone }: { a: ApprovalView; outcome: ApprovalOutcome | null; onDone?: () => void }) {
const status = outcome?.status ?? a.status;
const result = (outcome ?? (a.result as Record | null)) as {
batch?: number | null;
+ install_line?: string | null;
} | null;
if (status === "declined")
return (
@@ -60,7 +62,7 @@ function Outcome({ a, outcome }: { a: ApprovalView; outcome: ApprovalOutcome | n
– Declined: {a.summary}
);
- return (
+ const approved = (
✓
@@ -73,6 +75,24 @@ function Outcome({ a, outcome }: { a: ApprovalView; outcome: ApprovalOutcome | n
)}
);
+ // a new mesh node's install line, in the answer to this approval only: it's never kept
+ if (!result?.install_line) return approved;
+ return (
+
+ {approved}
+
+ Run it on the machine; it shows in Settings › Nodes when it joins. The line isn’t shown again.
+
+
+ {onDone && (
+
+
+
+ )}
+
+ );
}
/**
@@ -104,16 +124,16 @@ export function ApprovalCard({
body: { decision },
}),
),
- onSuccess: () => {
+ onSuccess: (out) => {
void qc.invalidateQueries({ queryKey: ["approvals", chatId] });
- onDecided?.();
+ if (!out?.install_line) onDecided?.(); // a line shown once stays until the person is done with it
},
});
const decided = decide.data ?? null;
if ((a.status && a.status !== "pending") || decided)
return (
- Agents do the same over /api/v1/mesh: nodes, tokens and the network. A node
- joins, renews its certificate and reports here; a worker node takes this install’s jobs, and a compute node runs
- the assistant’s code.
+ Agents do the same over /api/v1/mesh, MCP and the assistant: nodes, tokens
+ and the network; the assistant asks you before a machine joins or is taken off. A node joins, renews its
+ certificate and reports here; a worker node takes this install’s jobs, and a compute node runs the assistant’s
+ code.
>
);
diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json
index 0debfd932..1a5b472b3 100644
--- a/nextjs-frontend/openapi.json
+++ b/nextjs-frontend/openapi.json
@@ -37966,6 +37966,18 @@
],
"title": "Always",
"description": "that node runs without asking from now on"
+ },
+ "install_line": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Install Line",
+ "description": "the line to run on the new machine, for add_mesh_node: shown this once and not kept"
}
},
"additionalProperties": true,
diff --git a/threat-model.json b/threat-model.json
index b2548ca99..7b3173834 100644
--- a/threat-model.json
+++ b/threat-model.json
@@ -148,7 +148,7 @@
"/api/v1/mesh/node/config, /node/renew, /node/beat (a node's own calls, with its node token)",
"GET /api/v1/mesh/node/worker, /node/media/{id} (a worker node's database user and its jobs' files, with its node token)",
"PUT /api/v1/mesh/node/sandbox (a compute node's sandbox gateway's client certificate, with its node token), and Lens's calls to that gateway on the node's mesh address, port 7443",
- "POST /api/v1/mesh/tokens, PATCH and DELETE /api/v1/mesh/nodes/{id}, PUT /api/v1/settings/mesh",
+ "POST /api/v1/mesh/tokens, PATCH and DELETE /api/v1/mesh/nodes/{id}, PUT /api/v1/settings/mesh, MCP and assistant mesh tools",
"UDP 4242 on the primary and ports 8000 and 8080 on its mesh address (the mesh container, while the mesh is on)"
],
"touches": [
@@ -813,11 +813,11 @@
"source": "docs/mesh.md \"Compute nodes\""
},
{
- "entry_point": "POST /api/v1/mesh/tokens, PATCH and DELETE /api/v1/mesh/nodes/{id}, PUT /api/v1/settings/mesh",
+ "entry_point": "POST /api/v1/mesh/tokens, PATCH and DELETE /api/v1/mesh/nodes/{id}, PUT /api/v1/settings/mesh, MCP and assistant mesh tools",
"parameter": "a node's role, name, namespaces, token hours and uses; the mesh's network, port, hosts, cipher",
"attacker_controllable": "no",
"component": "optional",
- "caller_must_enforce": "admin is trusted; audited (mesh.token.create, mesh.join, mesh.node.*); the network can't change once machines have addresses in it",
+ "caller_must_enforce": "admin is trusted; audited (mesh.token.create, mesh.join, mesh.node.*); the network can't change once machines have addresses in it; the assistant's adding and removing a node always wait for the person's approval; an install line (it holds a join token's secret) goes only to the MCP agent that asked or to the person who approved, once, and is never kept in an approval, the audit log or the model's context; the read tools never show a token's secret",
"provenance": "documented",
"source": "docs/mesh.md \"Settings\""
},
diff --git a/threat-model.md b/threat-model.md
index 8860976a8..02ad0899a 100644
--- a/threat-model.md
+++ b/threat-model.md
@@ -338,7 +338,7 @@ classified by gate only *(inferred, Q8)*; unread modules are listed in Q34.
| `/api/v1/mesh/node/config`, `/node/renew`, `/node/beat` (a node's own calls, with its node token) | a public key to certify; a status report: whether Nebula runs, its peers, its machine, its log lines | yes, a machine that joined (a removed one is refused) | x-credential, data, x-peer | the node token is 256 random bits kept only as a hash; a node gets its own config and a certificate for its own address and groups only, and can't widen them; reports are capped and kept as its status for admins; they arrive at the primary's mesh address, which the API's host check admits for these paths alone while the mesh is on | *(documented, docs/mesh.md "After joining")* |
| `GET /api/v1/mesh/node/worker`, `/node/media/{id}` (a worker node's database user and its jobs' files, with its node token) | a recording id; the node's role and namespaces | yes, a worker node that joined (a removed one is refused) | x-credential, data, x-peer | worker nodes only (403 for others); the database user (`lens_node_`) owns Lens's database and nothing else on the server, never root, is removed with the node and made again with a new password on an undo, and isn't kept on the node's disk; files are those of the namespaces the node serves, never a vault's, sent plain over the mesh and cached on the node for 6 hours; the archive's secret never leaves the primary | *(documented, docs/mesh.md "Worker nodes")* |
| `PUT /api/v1/mesh/node/sandbox` (a compute node's sandbox gateway's client certificate, with its node token), and Lens's calls to that gateway on port 7443 of the node's mesh address | a CA certificate, a client certificate and its key, PEM | yes, a compute node that joined (a removed one is refused) | x-credential, x-peer | compute nodes only (403 for others); each part capped and loaded as a certificate or key (400 otherwise); the key kept sealed like a setting's secret; Lens reaches the gateway over the mesh only (Nebula's firewall opens 7443 to the primary only, and the node's mesh container relays it to the gateway), with mutual TLS checked against the name the gateway's certificate was made for; a compute node gets nothing of Lens's in return | *(documented, docs/mesh.md "Compute nodes")* |
-| `POST /api/v1/mesh/tokens`, `PATCH` and `DELETE /api/v1/mesh/nodes/{id}`, `PUT /api/v1/settings/mesh` | a node's role, name, namespaces, token hours and uses; the mesh's network, port, hosts, cipher | admin only | x-env-config | admin is trusted; audited (`mesh.token.create`, `mesh.join`, `mesh.node.*`); the network can't change once machines have addresses in it | *(documented, docs/mesh.md "Settings")* |
+| `POST /api/v1/mesh/tokens`, `PATCH` and `DELETE /api/v1/mesh/nodes/{id}`, `PUT /api/v1/settings/mesh`, MCP and assistant mesh tools (`mesh`, `add_mesh_node`, `change_mesh_node`, `remove_mesh_node`, `restore_mesh_node`, `withdraw_mesh_token`) | a node's role, name, namespaces, token hours and uses; the mesh's network, port, hosts, cipher | admin only (MCP: with the write scope) | x-env-config, x-credential | admin is trusted; audited (`mesh.token.create`, `mesh.join`, `mesh.node.*`); the network can't change once machines have addresses in it; the assistant's adding and removing a node always wait for the person's approval; an install line (it holds a join token's secret) goes only to the MCP agent that asked or to the person who approved, once, and is never kept in an approval, the audit log or the model's context; the read tools never show a token's secret | *(documented, docs/mesh.md "Settings")* |
| UDP 4242 on the primary and ports 8000 and 8080 on its mesh address (the `mesh` container, while the mesh is on) | Nebula handshakes and tunnelled packets from anyone reaching the port; on the mesh, TCP to the database and the API | yes, anyone reaching UDP 4242; on the mesh, a machine with a certificate the mesh's CA signed | data, x-peer | Nebula drops what no certificate of the mesh's CA signs and anything on the blocklist; its firewall, rendered by Lens, lets only `lens-worker` reach 8000 and `lens-node` 8080; the relays listen on the mesh address only; the container is the only one holding NET_ADMIN, makes its own key pair (the private key stays in its own volume) and runs only Nebula's release with the checksum kept in Lens | *(documented, docs/mesh.md "On this machine")* |
**Stateful postconditions.** A refused or failed one-time secret check consumes nothing; a used one is deleted before
diff --git a/threat-model.yaml b/threat-model.yaml
index 45432b11c..4cdc6ed90 100644
--- a/threat-model.yaml
+++ b/threat-model.yaml
@@ -605,14 +605,14 @@ entry_points:
control_kinds: [x-credential, x-peer]
caller_must_enforce: "compute nodes only (403 for others); each part capped and loaded as a certificate or key (400 otherwise); the key kept sealed like a setting's secret; Lens reaches the gateway over the mesh only (7443 open to the primary only, relayed to the gateway by the node's mesh container), with mutual TLS checked against the name the gateway's certificate was made for; the node gets nothing of Lens's"
provenance: {kind: documented, source: 'docs/mesh.md "Compute nodes"'}
- - id: "POST /api/v1/mesh/tokens, PATCH and DELETE /api/v1/mesh/nodes/{id}, PUT /api/v1/settings/mesh"
+ - id: "POST /api/v1/mesh/tokens, PATCH and DELETE /api/v1/mesh/nodes/{id}, PUT /api/v1/settings/mesh, MCP and assistant mesh tools"
component: optional
parameters:
- name: "a node's role, name, namespaces, token hours and uses; the mesh's network, port, hosts, cipher"
attacker_controllable: false
- x-condition: "admin only"
- control_kinds: [x-env-config]
- caller_must_enforce: "admin is trusted; audited (mesh.token.create, mesh.join, mesh.node.*); the network can't change once machines have addresses in it"
+ x-condition: "admin only (MCP: with the write scope)"
+ control_kinds: [x-env-config, x-credential]
+ caller_must_enforce: "admin is trusted; audited (mesh.token.create, mesh.join, mesh.node.*); the network can't change once machines have addresses in it; the assistant's adding and removing a node always wait for the person's approval; an install line (it holds a join token's secret) goes only to the MCP agent that asked or to the person who approved, once, and is never kept in an approval, the audit log or the model's context; the read tools never show a token's secret"
provenance: {kind: documented, source: 'docs/mesh.md "Settings"'}
- id: "UDP 4242 on the primary and ports 8000 and 8080 on its mesh address (the mesh container, while the mesh is on)"
component: optional