feat: add relay-native execution nodes

[Onnokh]

First, great work on the remote-agent direction so far, especially the discussion and specification in #3748.

Over the past couple of days, I’ve been working on a relay-native execution-node approach, and it happened to converge with many of the same questions and constraints that emerged in the discussion around this PR and the related work.

This is intentionally an early exploration rather than a finished or settled architecture. I’m sharing it to make the direction concrete and see how well it fits with the Buzz vision and the provider model.

Summary

This PR introduces buzz-node: a standalone, relay-native execution node for running Buzz agents away from the desktop.

The goal is to let the same Buzz agent continue existing on remote or persistent infrastructure while preserving the normal Buzz model:

• the agent identity remains on the relay;
• the agent uses the same relay, history, channels, and desktop UI;
• the machine is only an execution body;
• runtime-specific details stay behind a substrate boundary.

This is intended to address the hosted and persistent agent direction discussed in #4174.

Motivation

Remote agents currently lead toward several separate solutions: provider-specific launchers, host-specific supervisors, custom control APIs, and one-off integrations for Docker, SSH, Kubernetes, and local processes.

That risks creating a different product model for every execution environment.

I’m exploring a shared execution-node model instead. A node is a relay-connected Buzz principal that can be paired with an owner, receive authorized lifecycle commands, run workloads through a local substrate, and publish status and receipts back through the relay.

The agent itself remains the same agent. Only its execution body changes.

Architecture

The lifecycle is divided into a few clear responsibilities:

1. Desktop creates or selects a managed-agent identity using the existing agent model.

2. An execution node is paired with the owner through the relay and receives its own persistent Nostr identity.

3. Desktop publishes encrypted workload commands to the node through the relay. Commands include deployment, start, stop, restart, removal, and provider-authentication operations.

4. The node authenticates the command, verifies the owner/node/relay binding, applies idempotency and sequencing checks, and reconciles the requested workload state.

5. A runtime-neutral substrate starts the agent body. The initial substrates are local processes and Docker containers, using the same ACP/runtime contract used by Desktop.

6. The node publishes encrypted receipts and safe workload status through the relay. Desktop uses those results to present the remote agent alongside other agents.

Node availability is represented through normal Buzz presence. The node announcement contains slower-moving identity, capability, pairing, and workload information; presence represents whether the node is currently connected.

Security and lifecycle boundaries

The node is deliberately relay-first:

• Desktop does not maintain a second management connection to the host.
• Commands and receipts are encrypted for their intended participants.
• Pairing binds the node to an owner and relay authority.
• Raw provider credentials are not included in workload configuration.
• Credential material remains node-local.
• Workload commands are bounded, sequenced, and idempotent.
• The node persists its identity, pairing state, workload ledger, and command journal.
• Runtime details such as Docker, process supervision, images, and environment setup stay outside the shared relay protocol.

The relay is the coordination plane. The node is the execution participant. The substrate only runs the requested workload.

Relationship to the remote-agent specification

This builds on the direction established by #3748:

• the relay remains the post-deploy coordination plane;
• the agent identity is independent of the machine running it;
• execution environments are replaceable;
• presence is used for conversational availability;
• runtime and substrate details are kept behind a narrow boundary.

The part this PR explores further is the Buzz-specific substrate model discussed in the PR conversation: making the execution environment itself a relay-registered principal with an identity, pairing relationship, lifecycle protocol, and relay-visible status.

This is intended to complement the generic provider model rather than create a second agent model.

Current scope

This PR currently includes:

• standalone buzz-node service;
• persistent node identity and state;
• Desktop pairing;
• relay-native encrypted commands and receipts;
• owner and relay-bound authorization;
• durable workload reconciliation and idempotency;
• Desktop execution-node discovery;
• remote agent deployment and lifecycle controls;
• process and Docker substrates;
• provider-authentication handoff;
• node presence and readiness reporting.

PR size

I recognize that this is a substantial PR with a broad surface area and a lot of change to review at once. The main review areas are approximately:

• buzz-node and the implemented process/Docker substrates: ~6.8k lines
• Shared execution protocol: ~1.9k lines
• Desktop integration: ~2k lines
• Execution and end-to-end tests: ~1.7k lines

Open questions

I’m sharing this implementation to discuss whether this is the right Buzz-specific layer for hosted and persistent agents:

• Should buzz-node become the common relay-native execution model across substrates?
• How should it relate to the generic provider contract from #3748?
• Which parts should be standardized as relay protocol versus substrate-specific behavior?
• Are the current pairing, lifecycle, status, and credential boundaries aligned with the broader Buzz vision?

[Onnokh]

Implementation walkthrough

I kept the PR description focused on the motivation and architectural direction. This comment captures the current implementation shape.

The Desktop integration is intended to preserve the existing agent model while making the execution body selectable. The agent configuration still shows the normal runtime and ACP command, while indicating that the agent runs on a connected Buzz execution node and remains owner-controlled.

Agent configuration

Selecting the execution body

The current Desktop flow allows the agent to run on this computer or on a connected execution node.

Relay protocol

The execution-node protocol currently uses:

• kind 30630 for replaceable node announcements;
• kind 20001 presence for live node availability;
• encrypted kind 24201 commands addressed to a node;
• encrypted kind 24202 receipts returned by the node.

The announcement contains the node identity, capabilities, pairing attestations, and safe workload status. Presence remains the availability signal rather than host telemetry.

Command lifecycle

Desktop sends encrypted commands through the relay. The node then:

1. verifies the command envelope and expiry;
2. verifies the owner, node, and relay binding;
3. checks command idempotency and sequencing;
4. reconciles the requested workload state;
5. publishes a sequenced receipt.

The current command set covers deployment, start, stop, restart, removal, and provider authentication.

The workload projection intentionally contains only safe execution data. Runtime-specific infrastructure, container details, and raw credentials remain node-local.

Runtime boundary

buzz-node currently has two implemented substrates:

• the process substrate launches and supervises buzz-acp bodies;
• the Docker substrate launches agent bodies as containers and supervises them through the Docker runtime.

Both use the same relay, identity, runtime, and environment contract as Desktop. The node protocol does not need to know whether the body is a process or a container.

Identity and credentials

The agent identity remains the managed agent’s identity. The execution node has a separate persistent Nostr identity used for relay authentication, announcements, commands, and receipts.

Nodes are paired with owners through the relay. Provider credentials remain node-local and are referenced by workloads rather than transmitted as ordinary workload configuration.

The process substrate keeps the launch key in memory and therefore requires redeployment after a node restart. The Docker substrate uses the running container as the key store, allowing lifecycle operations to survive a node restart while still failing closed if the container is gone.

Desktop integration

Desktop discovers paired nodes through their announcements and derives their live availability from presence. A managed agent can then be assigned to an execution node while retaining the same identity, profile, channels, history, and agent-facing UI as a locally running agent.

The intention is that “remote” changes where the body runs, not what kind of agent it is.

I expect the protocol and substrate boundaries to evolve as this is reviewed. The main question I’m trying to answer with this implementation is whether this is the right relay-native execution layer to standardize across hosted and persistent substrates.

[wolfyy970]

@Onnokh, I think the node is the better execution target. It keeps the agent identity stable and makes Run on a real product choice, so I want to adapt #4301 around it rather than build a competing remote path.

One boundary needs aligning before this grows. Merged #3748 now gives local and provider-backed agents one place to resolve the command, arguments, layered environment and launch policy. AgentWorkloadContext creates a second projection for nodes, so later Skills, MCP and workspace work would need to be wired twice and could drift.

Could WorkloadSpec carry that shared launch contract, plus a configuration version and node-local credential references? Then Run on changes where the agent runs, not which setup it gets. If that fits, I can adapt #4301 around it and help extract the shared type.

[Onnokh]

@wolfyy970 That feels like the right next step to me. I agree that the node is the better execution target, and that “Run on” should change where the agent runs rather than which configuration it receives.

I think the convergence seam is the launch contract that Desktop already resolves today through EffectiveHarnessDescriptor and serializes into the provider launch block. The next step should be to promote that into a shared buzz-core type and carry it with the execution workload, together with a configuration version and node-local credential references.

I don’t want to add launch alongside another active configuration path. The goal should be for local spawn, provider deployment, and buzz-node to consume the same resolved command, arguments, environment, and launch policy. The process and Docker substrates would then only adapt that contract to their runtime environment instead of reconstructing it from runtime and AgentRuntimeSettings.

That should also let us remove the duplicate node-side runtime inference and the separate provider launch type, while keeping substrate-specific supervision and persistence where they belong.

I could draft the follow-up later today.

[Onnokh]

@wolfyy970

WorkloadSpec now carries a versioned LaunchSpec in buzz-core — the same block providers already consume, evolved additively (snake_case wire shape unchanged).

Desktop resolves it once; local spawn, provider deploy, and node deploy all consume the same contract. Run on changes where the agent runs, not which setup it gets.
Substrates only adapt (paths, images, supervision) — the node-side runtime inference and AgentRuntimeSettings are deleted.
Provider credentials are stripped at the node boundary (PROVIDER_CREDENTIAL_ENV) and stay node-local; credential_refs is the anchor for a secret-store follow-up.
The restart badge now hashes the contract itself.

For #4301, the seam is resolve_launch_spec → LaunchSpec. Happy to extract more into buzz-core if you need pieces it doesn't carry yet.

[wolfyy970]

Thanks. This is the shared execution boundary I was hoping for. I’ll rebase the Project-binding work onto LaunchSpec and flag any missing configuration fields as concrete follow-ups.

[wolfyy970]

@Onnokh, I compared the new contract with the Project-binding and portable-agent work. The remaining shared pieces I need are:

• an immutable configuration revision or digest, separate from LaunchSpec.version, so updates and rollbacks identify the exact setup;
• structured MCP server definitions, with credential references bound to the inputs they populate. The executing machine resolves those references locally, so raw credentials never travel;
• Project and workspace context beyond the channel ID, without carrying machine-specific paths;
• pinned Skill bundle references with a version or digest, materialized by the executing machine.

I want resolve_launch_spec to resolve the complete execution configuration once. Local spawn, providers and nodes should only supply paths, credentials and runtime packaging. An agent can then keep the same instructions, Skills and tools when Run on changes, while updates and rollbacks compare one exact configuration.

If you want to take these shared types in #4597 or a follow-up, I’ll build #4301 and #4588 against them. If some belong elsewhere, tell me where you think the boundary should sit and I’ll adapt.

[wolfyy970]

@tlongwell-block, I want to check this against the remote-agent direction that has already landed.

#3748 and #3924 make provider deployment the generic path and deliberately avoid a substrate management channel after deploy. #4597 adds a relay-addressable execution node with deploy, start, stop and restart commands. I can see that working as a Buzz-specific execution target, but it is a different management model.

I am building the portable configuration side in #4301: one resolved setup for instructions, Skills, Project-bound tools and updates, independent of where it runs. Should I treat LaunchSpec as the stable provider-neutral boundary and the node as another consumer if it lands, or is #4597 intended to evolve the provider model? That decision changes where I put the Project and rollout integration, so I would rather align it now.