You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by wy...@apache.org on 2026/08/27 05:45:14 UTC

(maka) branch main updated: feat(desktop): onboard experimental direct peer hosts (#3950)

This is an automated email from the ASF dual-hosted git repository.

M4n5ter pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/maka.git


The following commit(s) were added to refs/heads/main by this push:
     new 5cde1fbe4 feat(desktop): onboard experimental direct peer hosts (#3950)
5cde1fbe4 is described below

commit 5cde1fbe413b722b2da4d7cbac19f9fc4d30c8b6
Author: Wang <m4...@gmail.com>
AuthorDate: Thu Aug 27 13:45:10 2026 +0800

    feat(desktop): onboard experimental direct peer hosts (#3950)
    
    * feat(desktop): onboard experimental direct peer hosts
    
    Manage the peer listener through the existing SSH channel while keeping SSH and Direct as separate Host profiles. Ship the native peer client in Desktop artifacts and verify the complete managed flow.
    
    Generated-by: OpenAI Codex
    
    * fix(desktop): preserve direct peer credential authority
    
    Refresh each managed Direct profile from its SSH credential authority before activation. Narrow the Desktop snapshot and framed peer protocol to the states their consumers actually use.
    
    Generated-by: OpenAI Codex
    
    * refactor(desktop): keep direct root authority in SSH profile
    
    Stop round-tripping the SSH profile's Root ID through the peer descriptor before recreating the same fact locally. Direct profiles now inherit their Root ID only from the managed SSH source.
    
    Generated-by: OpenAI Codex
    
    * fix(desktop): close Direct peer recovery gaps
    
    Compensate failed post-enable setup and keep remote disable available. Preserve the SSH management authority while Direct exists, and negotiate peer-management support before invoking it.
    
    Generated-by: OpenAI Codex
---
 .github/workflows/release-windows-check.yml        |   8 +
 .github/workflows/release.yml                      |   3 +
 apps/desktop/electron-builder.config.mjs           |   8 +
 .../main/__tests__/runtime-host-management.test.ts | 253 +++++++++++++++++++++
 .../__tests__/runtime-host-profile-service.test.ts |  92 ++++++++
 .../__tests__/runtime-host-ssh-terminal.test.ts    |   4 +-
 apps/desktop/src/main/runtime-host-boot.ts         |   9 +
 apps/desktop/src/main/runtime-host-management.ts   | 200 ++++++++++++++++
 apps/desktop/src/main/runtime-host-peer-client.ts  |  59 +++++
 .../src/main/runtime-host-profile-service.ts       | 199 +++++++++++++++-
 apps/desktop/src/main/runtime-host-ssh-terminal.ts |  51 ++++-
 apps/desktop/src/preload/bridge-contract.d.ts      |  17 ++
 apps/desktop/src/preload/preload.ts                |  15 ++
 .../src/renderer/locales/settings-projects-copy.ts |  60 +++++
 .../settings/runtime-host-management-dialog.tsx    | 177 ++++++++++++++
 .../settings/runtime-host-profiles-section.tsx     |  97 ++++----
 .../src/renderer/styles/settings/runtime-host.css  |   3 +-
 docs/runtime-host-remote-access.md                 |   9 +-
 docs/runtime-host-remote-access.zh-CN.md           |   7 +-
 .../__tests__/runtime-host-service-manager.test.ts |  46 ++++
 packages/cli/src/cli-core.ts                       |   1 +
 packages/cli/src/runtime-host-cli.ts               |   6 +
 .../src/runtime-host-peer-management-command.ts    |  47 ++--
 .../src/runtime-host-service-management-command.ts |   2 +
 .../src/__tests__/peer-management-frame.test.ts    |  44 ++++
 packages/runtime-host/src/operator/index.ts        |   9 +
 .../src/operator/peer-management-frame.ts          |  97 ++++++++
 .../src/operator/service-management-frame.ts       |   6 +-
 scripts/package-macos-arm64.mjs                    |   2 +
 scripts/package-windows-x64.mjs                    |   2 +
 scripts/verify-packaged-app.mjs                    |   9 +
 scripts/verify-packaged-app.test.mjs               |   1 +
 scripts/verify-windows-x64.mjs                     |   1 +
 33 files changed, 1464 insertions(+), 80 deletions(-)

diff --git a/.github/workflows/release-windows-check.yml b/.github/workflows/release-windows-check.yml
index b9af2e82a..27f00430d 100644
--- a/.github/workflows/release-windows-check.yml
+++ b/.github/workflows/release-windows-check.yml
@@ -32,7 +32,12 @@ on:
     paths:
       - 'apps/desktop/electron-builder.config.mjs'
       - 'apps/desktop/package.json'
+      - 'native/runtime-host-peer/**'
+      - 'packages/cli/RUNTIME_HOST_PEER_DEPENDENCIES.rust.tsv'
+      - 'packages/cli/RUNTIME_HOST_PEER_THIRD_PARTY_NOTICES.txt'
       - 'scripts/package-windows-x64.mjs'
+      - 'scripts/generate-runtime-host-peer-dependencies.mjs'
+      - 'scripts/generate-runtime-host-peer-notices.mjs'
       - 'scripts/verify-windows-x64.mjs'
       - 'scripts/verify-windows-sandbox-e2e.mjs'
       - 'scripts/verify-windows-installer-lifecycle.mjs'
@@ -119,6 +124,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Update stable Rust for Desktop native artifacts
+        run: rustup update stable --no-self-update
+
       - name: Package the Windows installer and ZIP
         run: npm run package:windows-x64
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 32d10e180..bf7e5eb18 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -137,6 +137,9 @@ jobs:
       - name: Audit shipped desktop closure
         run: node scripts/audit-shipped-dependencies.mjs
 
+      - name: Update stable Rust for Desktop native artifacts
+        run: rustup update stable --no-self-update
+
       - name: Write App Store Connect API key
         if: matrix.platform == 'macos'
         env:
diff --git a/apps/desktop/electron-builder.config.mjs b/apps/desktop/electron-builder.config.mjs
index 097effb35..3235bedac 100644
--- a/apps/desktop/electron-builder.config.mjs
+++ b/apps/desktop/electron-builder.config.mjs
@@ -89,6 +89,14 @@ export default {
       from: 'resources/workers/filesystem-worker.js',
       to: 'workers/filesystem-worker.js',
     },
+    {
+      from: '../../native/runtime-host-peer/target/release/maka_runtime_host_peer.node',
+      to: 'runtime-host-peer/maka_runtime_host_peer.node',
+    },
+    {
+      from: '../../packages/cli/RUNTIME_HOST_PEER_THIRD_PARTY_NOTICES.txt',
+      to: 'licenses/runtime-host-peer/THIRD_PARTY_NOTICES.txt',
+    },
     ...(process.platform === 'win32'
       ? [
           {
diff --git a/apps/desktop/src/main/__tests__/runtime-host-management.test.ts b/apps/desktop/src/main/__tests__/runtime-host-management.test.ts
index 2c30c6da1..1554bd0f7 100644
--- a/apps/desktop/src/main/__tests__/runtime-host-management.test.ts
+++ b/apps/desktop/src/main/__tests__/runtime-host-management.test.ts
@@ -20,6 +20,7 @@
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import {
+  RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
   runtimeHostAccessCredentialFingerprint,
   type RuntimeHostServiceManagementFrame,
 } from '@maka/runtime-host/operator';
@@ -73,6 +74,7 @@ test('identifies, rotates, and revokes managed credentials without exposing secr
       removeHandler: (channel) => handlers.delete(channel),
     },
     profiles: {
+      ...unusedDirectPeerProfileDependencies(),
       resolveManagedService: async () => ({ profile, service, state: 'active' as const }),
       resolveManagedAccess: async () => ({
         profile,
@@ -215,6 +217,7 @@ test('manages only the service identity bound by Desktop onboarding', async () =
       removeHandler: (channel) => handlers.delete(channel),
     },
     profiles: {
+      ...unusedDirectPeerProfileDependencies(),
       resolveManagedService: async (profileId) =>
         profileId === managedProfile.id
           ? { profile: managedProfile, service: managedService, state: 'active' as const }
@@ -361,6 +364,7 @@ test('publishes update progress and waits for the managed profile to reconnect',
       removeHandler: (channel) => handlers.delete(channel),
     },
     profiles: {
+      ...unusedDirectPeerProfileDependencies(),
       resolveManagedService: async () =>
         bindingPresent ? { profile, service, state: 'active' as const } : undefined,
       resolveManagedAccess: async () => undefined,
@@ -370,6 +374,8 @@ test('publishes update progress and waits for the managed profile to reconnect',
       clearManagedServiceBinding: async () => undefined,
     },
     runServiceManagement: async () => assert.fail('ordinary management is not expected'),
+    runPeerManagement: async () => assert.fail('direct peer management is not expected'),
+    directPeerClientAvailable: false,
     runUpdate: async (input, onProgress) => {
       updates.push(input);
       onProgress('staging');
@@ -481,6 +487,7 @@ test('configures Project roots with CAS and reconnects only after a committed cu
       removeHandler: (channel) => handlers.delete(channel),
     },
     profiles: {
+      ...unusedDirectPeerProfileDependencies(),
       resolveManagedService: async () => ({ profile, service, state: 'active' as const }),
       resolveManagedAccess: async () => undefined,
       rotateManagedCredential: async () => assert.fail('credential rotation is not expected'),
@@ -588,6 +595,7 @@ test('manages one Host update policy and reconciles it through the bound operato
       removeHandler: (channel) => handlers.delete(channel),
     },
     profiles: {
+      ...unusedDirectPeerProfileDependencies(),
       resolveManagedService: async () => ({ profile, service, state: 'active' as const }),
       resolveManagedAccess: async () => undefined,
       rotateManagedCredential: async () => assert.fail('credential rotation is not expected'),
@@ -733,6 +741,7 @@ test('resumes deployment cleanup without invoking the removed operator', async (
       removeHandler: (channel) => handlers.delete(channel),
     },
     profiles: {
+      ...unusedDirectPeerProfileDependencies(),
       resolveManagedService: async () => ({ profile, service, state }),
       resolveManagedAccess: async () => undefined,
       markManagedServiceUninstalling: async (binding) => {
@@ -785,6 +794,7 @@ test('rechecks uninstall intent before retrying the remote service', async () =>
       removeHandler: (channel) => handlers.delete(channel),
     },
     profiles: {
+      ...unusedDirectPeerProfileDependencies(),
       resolveManagedService: async () => ({
         profile: {
           id: 'office',
@@ -834,6 +844,235 @@ test('rechecks uninstall intent before retrying the remote service', async () =>
   assert.equal(marked, true);
 });
 
+test('keeps the SSH profile while adding and removing its managed Direct peer', async () => {
+  const handlers = new Map<string, (...args: unknown[]) => unknown>();
+  const profile = {
+    id: 'office',
+    name: 'Office',
+    kind: 'remote' as const,
+    rootId: 'a'.repeat(64),
+    transport: {
+      kind: 'ssh' as const,
+      destination: 'operator@example.com',
+      remotePort: 7443,
+      websocketPath: '/runtime-host',
+    },
+  };
+  const service = {
+    id: 'b'.repeat(64),
+    rootPath: '/srv/maka',
+    operatorPath: '/home/operator/.local/share/maka/operator',
+  };
+  let peerProfileExists = false;
+  const actions: string[] = [];
+
+  createDesktopRuntimeHostManagement({
+    ...unusedUpdateDependencies(),
+    ipcMain: {
+      handle: (channel, handler) => handlers.set(channel, handler as (...args: unknown[]) => unknown),
+      removeHandler: (channel) => handlers.delete(channel),
+    },
+    profiles: {
+      ...unusedDirectPeerProfileDependencies(),
+      resolveManagedService: async () => ({ profile, service, state: 'active' as const }),
+      resolveManagedAccess: async () => undefined,
+      rotateManagedCredential: async () => assert.fail('credential rotation is not expected'),
+      markManagedServiceUninstalling: async (binding) => binding,
+      markManagedServiceCleanupPending: async (binding) => binding,
+      clearManagedServiceBinding: async () => undefined,
+      resolveManagedDirectPeerProfile: async () => ({
+        exists: peerProfileExists,
+        enabled: false,
+      }),
+      upsertManagedDirectPeerProfile: async (_profileId, descriptor) => {
+        assert.deepEqual(descriptor.routeHints, ['/ip4/192.0.2.8/udp/44001/quic-v1']);
+        peerProfileExists = true;
+      },
+      removeManagedDirectPeerProfile: async () => {
+        peerProfileExists = false;
+      },
+    },
+    directPeerClientAvailable: true,
+    runServiceManagement: async (input) => {
+      assert.equal(input.action, 'status');
+      assert.equal(
+        input.capabilityRequest,
+        RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
+      );
+      return {
+        ...serviceResult('status'),
+        operatorCapabilities: [RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY],
+      };
+    },
+    runAccessManagement: async () => assert.fail('access management is not expected'),
+    runPeerManagement: async (input) => {
+      actions.push(input.action);
+      return {
+        kind: 'result',
+        action: input.action,
+        status: input.action === 'disable'
+          ? {
+              state: 'not_configured',
+              serviceState: 'running',
+              routeHints: [],
+              coordinationRelays: [],
+            }
+          : {
+              state: 'enabled',
+              serviceState: 'running',
+              peerId: '12D3KooWpeer',
+              rootId: profile.rootId,
+              routeHints: ['/ip4/192.0.2.8/udp/44001/quic-v1'],
+              coordinationRelays: [],
+            },
+      };
+    },
+    cleanupManagedDeployment: async () => assert.fail('cleanup is not expected'),
+  });
+
+  const configure = handlers.get('runtime-host-management:configure-direct-peer');
+  assert.ok(configure);
+  const enabled = await configure({}, profile.id, true, []);
+  assert.equal((enabled as { profilePresent: boolean }).profilePresent, true);
+  const disabled = await configure({}, profile.id, false, []);
+  assert.equal((disabled as { profilePresent: boolean }).profilePresent, false);
+  assert.deepEqual(actions, ['enable', 'disable']);
+});
+
+test('disables a newly enabled listener when its Desktop profile cannot be committed', async () => {
+  for (const failure of ['descriptor', 'persistence'] as const) {
+    const handlers = new Map<string, (...args: unknown[]) => unknown>();
+    const actions: string[] = [];
+    createDesktopRuntimeHostManagement({
+      ...unusedUpdateDependencies(),
+      ipcMain: {
+        handle: (channel, handler) => handlers.set(channel, handler as (...args: unknown[]) => unknown),
+        removeHandler: (channel) => handlers.delete(channel),
+      },
+      profiles: {
+        ...unusedDirectPeerProfileDependencies(),
+        resolveManagedService: async () => managedSshBinding(),
+        resolveManagedAccess: async () => undefined,
+        rotateManagedCredential: async () => assert.fail('credential rotation is not expected'),
+        markManagedServiceUninstalling: async (binding) => binding,
+        markManagedServiceCleanupPending: async (binding) => binding,
+        clearManagedServiceBinding: async () => undefined,
+        resolveManagedDirectPeerProfile: async () => ({ exists: false, enabled: false }),
+        upsertManagedDirectPeerProfile: async () => {
+          if (failure === 'persistence') throw new Error('profile store failed');
+        },
+        removeManagedDirectPeerProfile: async () => undefined,
+      },
+      directPeerClientAvailable: true,
+      runServiceManagement: async () => ({
+        ...serviceResult('status'),
+        operatorCapabilities: [RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY],
+      }),
+      runAccessManagement: async () => assert.fail('access management is not expected'),
+      runPeerManagement: async (input) => {
+        actions.push(input.action);
+        return {
+          kind: 'result',
+          action: input.action,
+          status: input.action === 'disable'
+            ? {
+                state: 'disabled',
+                serviceState: 'running',
+                peerId: '12D3KooWpeer',
+                rootId: 'a'.repeat(64),
+                routeHints: [],
+                coordinationRelays: [],
+              }
+            : {
+                state: 'enabled',
+                serviceState: 'running',
+                peerId: '12D3KooWpeer',
+                rootId: 'a'.repeat(64),
+                routeHints: failure === 'descriptor' ? [] : ['/ip4/192.0.2.8/udp/44001/quic-v1'],
+                coordinationRelays: [],
+              },
+        };
+      },
+      cleanupManagedDeployment: async () => assert.fail('cleanup is not expected'),
+    });
+
+    const configure = handlers.get('runtime-host-management:configure-direct-peer');
+    assert.ok(configure);
+    await assert.rejects(
+      configure({}, 'office', true, []) as Promise<unknown>,
+      failure === 'descriptor' ? /usable direct-peer descriptor/u : /profile store failed/u,
+    );
+    assert.deepEqual(actions, ['enable', 'disable']);
+  }
+});
+
+test('does not invoke peer management when the remote operator lacks its capability', async () => {
+  const handlers = new Map<string, (...args: unknown[]) => unknown>();
+  createDesktopRuntimeHostManagement({
+    ...unusedUpdateDependencies(),
+    ipcMain: {
+      handle: (channel, handler) => handlers.set(channel, handler as (...args: unknown[]) => unknown),
+      removeHandler: (channel) => handlers.delete(channel),
+    },
+    profiles: {
+      ...unusedDirectPeerProfileDependencies(),
+      resolveManagedService: async () => managedSshBinding(),
+      resolveManagedAccess: async () => undefined,
+      rotateManagedCredential: async () => assert.fail('credential rotation is not expected'),
+      markManagedServiceUninstalling: async (binding) => binding,
+      markManagedServiceCleanupPending: async (binding) => binding,
+      clearManagedServiceBinding: async () => undefined,
+      resolveManagedDirectPeerProfile: async () => ({ exists: false, enabled: false }),
+    },
+    directPeerClientAvailable: true,
+    runServiceManagement: async () => serviceResult('status'),
+    runAccessManagement: async () => assert.fail('access management is not expected'),
+    runPeerManagement: async () => assert.fail('peer management is not expected'),
+    cleanupManagedDeployment: async () => assert.fail('cleanup is not expected'),
+  });
+
+  const get = handlers.get('runtime-host-management:get-direct-peer');
+  const configure = handlers.get('runtime-host-management:configure-direct-peer');
+  assert.ok(get);
+  assert.ok(configure);
+  assert.deepEqual(await get({}, 'office'), {
+    state: 'unsupported',
+    routeHints: [],
+    coordinationRelays: [],
+    profilePresent: false,
+    profileEnabled: false,
+    clientAvailable: true,
+    managementAvailable: false,
+  });
+  await assert.rejects(
+    configure({}, 'office', true, []) as Promise<unknown>,
+    /Update this Runtime Host/u,
+  );
+});
+
+function managedSshBinding() {
+  return {
+    profile: {
+      id: 'office',
+      name: 'Office',
+      kind: 'remote' as const,
+      rootId: 'a'.repeat(64),
+      transport: {
+        kind: 'ssh' as const,
+        destination: 'operator@example.com',
+        remotePort: 7443,
+        websocketPath: '/runtime-host',
+      },
+    },
+    service: {
+      id: 'b'.repeat(64),
+      rootPath: '/srv/maka',
+      operatorPath: '/home/operator/.local/share/maka/operator',
+    },
+    state: 'active' as const,
+  };
+}
+
 function serviceResult(
   action: DesktopRuntimeHostSshManagementInput['action'],
   operatorAccess = false,
@@ -884,6 +1123,9 @@ function unusedUpdateDependencies() {
     runUpdatePolicy: async (): Promise<never> => assert.fail('update policy is not expected'),
     runUpdateReconciliation: async (): Promise<never> =>
       assert.fail('update reconciliation is not expected'),
+    runPeerManagement: async (): Promise<never> =>
+      assert.fail('direct peer management is not expected'),
+    directPeerClientAvailable: false,
     resolveUpdatePackage: () => ({ kind: 'npm', specifier: 'maka-agent@1.2.3' } as const),
     currentHostEpoch: () => undefined,
     awaitUpdatedConnection: async () => undefined,
@@ -891,6 +1133,17 @@ function unusedUpdateDependencies() {
   };
 }
 
+function unusedDirectPeerProfileDependencies() {
+  return {
+    resolveManagedDirectPeerProfile: async (): Promise<never> =>
+      assert.fail('direct peer profile inspection is not expected'),
+    upsertManagedDirectPeerProfile: async (): Promise<never> =>
+      assert.fail('direct peer profile creation is not expected'),
+    removeManagedDirectPeerProfile: async (): Promise<never> =>
+      assert.fail('direct peer profile removal is not expected'),
+  };
+}
+
 function accessCredential(
   credentialId: string,
   principalId: string,
diff --git a/apps/desktop/src/main/__tests__/runtime-host-profile-service.test.ts b/apps/desktop/src/main/__tests__/runtime-host-profile-service.test.ts
index 3ccb04e3f..5fe96453b 100644
--- a/apps/desktop/src/main/__tests__/runtime-host-profile-service.test.ts
+++ b/apps/desktop/src/main/__tests__/runtime-host-profile-service.test.ts
@@ -523,6 +523,98 @@ test("finishes a persisted pairing after Desktop restarts before finalization",
   );
 });
 
+test("keeps a managed Direct route on the SSH profile credential authority", async () => {
+  const root = await clientRoot();
+  const catalog = createClientRuntimeHostProfileCatalog(root);
+  const managedServices = createDesktopRuntimeHostManagedServiceStore(root);
+  await catalog.create(MANAGED_PROFILE, "owner-token");
+  await managedServices.save(MANAGED_PROFILE, MANAGED_SERVICE);
+  const startup = await resolveDesktopRuntimeHostStartup(root, { catalog });
+  const activated: ResolvedRuntimeHostProfile[] = [];
+  const service = createDesktopRuntimeHostProfileService({
+    clientDataRoot: root,
+    startup,
+    catalog,
+    managedServices,
+    states: () => [connectingLocal()],
+    enable: async (target) => {
+      activated.push(target);
+    },
+    disable: async () => undefined,
+    setDefault: () => undefined,
+    finalizePairing: async () => undefined,
+  });
+
+  await service.upsertManagedDirectPeerProfile(MANAGED_PROFILE.id, {
+    peerId: "12D3KooWpeer",
+    routeHints: ["/ip4/192.0.2.8/udp/44001/quic-v1"],
+    coordinationRelays: [],
+  });
+
+  const directId = (await catalog.read()).profiles.find(
+    (profile) => profile.kind === 'remote' && profile.transport.kind === 'libp2p-direct',
+  )?.id;
+  assert.ok(directId);
+  const direct = await catalog.resolve(directId);
+  assert.equal(direct.credential, "owner-token");
+  assert.equal(direct.profile.kind, "remote");
+  if (direct.profile.kind !== "remote") assert.fail("expected a remote Direct profile");
+  assert.deepEqual(direct.profile.transport, {
+    kind: "libp2p-direct",
+    peerId: "12D3KooWpeer",
+    routeHints: ["/ip4/192.0.2.8/udp/44001/quic-v1"],
+    coordinationRelays: [],
+  });
+  assert.equal((await catalog.resolve(MANAGED_PROFILE.id)).credential, "owner-token");
+
+  const beforeRejectedRemoval = {
+    document: await catalog.read(),
+    source: await catalog.resolve(MANAGED_PROFILE.id),
+    direct: await catalog.resolve(directId),
+    managed: await managedServices.read(),
+    snapshot: await service.getSnapshot(),
+  };
+  const managedBinding = await service.resolveManagedService(MANAGED_PROFILE.id);
+  assert.ok(managedBinding);
+  await assert.rejects(
+    service.remove(MANAGED_PROFILE.id),
+    /remove the Direct peer profile/u,
+  );
+  await assert.rejects(
+    service.markManagedServiceUninstalling(managedBinding),
+    /remove the Direct peer profile/u,
+  );
+  assert.deepEqual(
+    {
+      document: await catalog.read(),
+      source: await catalog.resolve(MANAGED_PROFILE.id),
+      direct: await catalog.resolve(directId),
+      managed: await managedServices.read(),
+      snapshot: await service.getSnapshot(),
+    },
+    beforeRejectedRemoval,
+  );
+
+  await service.setEnabled(MANAGED_PROFILE.id, true);
+  const access = await service.resolveManagedAccess(MANAGED_PROFILE.id);
+  assert.ok(access);
+  await service.rotateManagedCredential(access, 'replacement-token');
+  await service.setEnabled(MANAGED_PROFILE.id, false);
+  await service.setEnabled(directId, true);
+
+  assert.equal((await catalog.resolve(directId)).credential, 'replacement-token');
+  assert.equal(activated.at(-1)?.profile.id, directId);
+  assert.equal(activated.at(-1)?.credential, 'replacement-token');
+
+  await service.setEnabled(directId, false);
+  await service.removeManagedDirectPeerProfile(MANAGED_PROFILE.id);
+
+  assert.deepEqual((await catalog.read()).profiles, [MANAGED_PROFILE]);
+  await service.remove(MANAGED_PROFILE.id);
+  assert.deepEqual((await catalog.read()).profiles, []);
+  assert.deepEqual((await managedServices.read()).bindings, []);
+});
+
 test("recovers interrupted managed credential rotation after restart", async () => {
   const root = await clientRoot();
   const catalog = createClientRuntimeHostProfileCatalog(root);
diff --git a/apps/desktop/src/main/__tests__/runtime-host-ssh-terminal.test.ts b/apps/desktop/src/main/__tests__/runtime-host-ssh-terminal.test.ts
index 348247983..ea66dedbe 100644
--- a/apps/desktop/src/main/__tests__/runtime-host-ssh-terminal.test.ts
+++ b/apps/desktop/src/main/__tests__/runtime-host-ssh-terminal.test.ts
@@ -31,6 +31,7 @@ import {
   encodeRuntimeHostServiceManagementFrame,
   encodeRuntimeHostSetupFrame,
   runtimeHostAccessCredentialFingerprint,
+  RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
   RUNTIME_HOST_SETUP_FRAME_PREFIX,
 } from '@maka/runtime-host/operator';
 import { createDesktopRuntimeHostSshTerminal } from '../runtime-host-ssh-terminal.js';
@@ -256,6 +257,7 @@ test('reads a framed service result without projecting it into the SSH terminal'
     destination: 'operator@example.com',
     operatorPath: '/home/operator/.local/share/maka/operator',
     action: 'status',
+    capabilityRequest: RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
     expectedTarget: {
       serviceId: 'b'.repeat(64),
       rootPath: '/home/operator/.config/Maka/workspaces/default',
@@ -266,7 +268,7 @@ test('reads a framed service result without projecting it into the SSH terminal'
   const remoteCommand = harness.launchArgs.at(-1)?.at(-1) ?? '';
   assert.match(remoteCommand, /\.local\/share\/maka\/operator/u);
   assert.match(remoteCommand, /MAKA_RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST/u);
-  assert.match(remoteCommand, /access-management-v1/u);
+  assert.match(remoteCommand, /peer-management-v1/u);
   assert.doesNotMatch(remoteCommand, /npx|maka-agent@/u);
   harness.pty.emitData('Password: ');
   harness.pty.emitData(
diff --git a/apps/desktop/src/main/runtime-host-boot.ts b/apps/desktop/src/main/runtime-host-boot.ts
index b9a3771e1..0c05fa693 100644
--- a/apps/desktop/src/main/runtime-host-boot.ts
+++ b/apps/desktop/src/main/runtime-host-boot.ts
@@ -169,6 +169,7 @@ import {
   createDesktopRuntimeHostSshTerminal,
 } from "./runtime-host-ssh-terminal.js";
 import { createRuntimeHostSetupPackageResolver } from "./runtime-host-setup-package.js";
+import { configureDesktopRuntimeHostPeerClient } from './runtime-host-peer-client.js';
 import { createDesktopRuntimeHostOnboarding } from "./runtime-host-onboarding.js";
 import { createDesktopRuntimeHostManagement } from "./runtime-host-management.js";
 import { registerRuntimeHostOAuthIpc } from "./runtime-host-oauth-ipc-main.js";
@@ -214,6 +215,12 @@ await resolveShellEnv();
 const MANAGED_UPDATE_RECONNECT_TIMEOUT_MS = 10_000;
 const buildInfo = resolveBuildInfo(app.isPackaged, app.getAppPath());
 const userDataDir = app.getPath("userData");
+const runtimeHostDirectPeerAvailable = await configureDesktopRuntimeHostPeerClient({
+  isPackaged: app.isPackaged,
+  appPath: app.getAppPath(),
+  resourcesPath: process.resourcesPath,
+  clientDataRoot: userDataDir,
+});
 const runtimeHostClientInstanceId = await loadOrCreateRuntimeHostClientInstanceId(
   join(userDataDir, "runtime-host-client.json"),
 );
@@ -452,6 +459,8 @@ const runtimeHostManagement = createDesktopRuntimeHostManagement({
   ipcMain,
   profiles: runtimeHostProfileService,
   runServiceManagement: runtimeHostSshTerminal.runServiceManagement,
+  runPeerManagement: runtimeHostSshTerminal.runPeerManagement,
+  directPeerClientAvailable: runtimeHostDirectPeerAvailable,
   runUpdate: runtimeHostSshTerminal.runUpdate,
   runUpdatePolicy: runtimeHostSshTerminal.runUpdatePolicy,
   runUpdateReconciliation: runtimeHostSshTerminal.runUpdateReconciliation,
diff --git a/apps/desktop/src/main/runtime-host-management.ts b/apps/desktop/src/main/runtime-host-management.ts
index dbf777e71..33bc920d7 100644
--- a/apps/desktop/src/main/runtime-host-management.ts
+++ b/apps/desktop/src/main/runtime-host-management.ts
@@ -20,14 +20,18 @@
 import type { IpcMain } from 'electron';
 import {
   RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY,
+  RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
   isProductReleaseVersion,
   runtimeHostAccessCredentialFingerprint,
   type RuntimeHostManagedUpdatePolicy,
   type RuntimeHostAccessManagementFrame,
+  type RuntimeHostPeerManagementFrame,
+  type RuntimeHostPeerStatus,
   type RuntimeHostServiceManagementFrame,
 } from '@maka/runtime-host/operator';
 import type {
   DesktopRuntimeHostAccessSnapshot,
+  DesktopRuntimeHostDirectPeerSnapshot,
   DesktopRuntimeHostManagementAction,
   DesktopRuntimeHostManagementResponse,
   DesktopRuntimeHostManagementProgress,
@@ -41,6 +45,7 @@ import type {
   DesktopRuntimeHostSshCleanupInput,
   DesktopRuntimeHostSshAccessInput,
   DesktopRuntimeHostSshManagementInput,
+  DesktopRuntimeHostSshPeerManagementInput,
   DesktopRuntimeHostSshUpdateInput,
   DesktopRuntimeHostSshUpdatePolicyInput,
   DesktopRuntimeHostSshUpdateReconciliationInput,
@@ -74,6 +79,9 @@ export function createDesktopRuntimeHostManagement(input: {
     | 'markManagedServiceUninstalling'
     | 'markManagedServiceCleanupPending'
     | 'clearManagedServiceBinding'
+    | 'resolveManagedDirectPeerProfile'
+    | 'upsertManagedDirectPeerProfile'
+    | 'removeManagedDirectPeerProfile'
   >;
   readonly runServiceManagement: (
     input: DesktopRuntimeHostSshManagementInput,
@@ -81,6 +89,10 @@ export function createDesktopRuntimeHostManagement(input: {
   readonly runAccessManagement: (
     input: DesktopRuntimeHostSshAccessInput,
   ) => Promise<RuntimeHostAccessManagementFrame>;
+  readonly runPeerManagement: (
+    input: DesktopRuntimeHostSshPeerManagementInput,
+  ) => Promise<RuntimeHostPeerManagementFrame>;
+  readonly directPeerClientAvailable: boolean;
   readonly runUpdate: (
     input: DesktopRuntimeHostSshUpdateInput,
     onProgress: (phase: DesktopRuntimeHostManagementProgress['phase']) => void,
@@ -260,6 +272,163 @@ export function createDesktopRuntimeHostManagement(input: {
     };
   };
 
+  const peerSnapshot = async (
+    profileId: string,
+    status: RuntimeHostPeerStatus,
+  ): Promise<DesktopRuntimeHostDirectPeerSnapshot> => {
+    const profile = await input.profiles.resolveManagedDirectPeerProfile(profileId);
+    return {
+      state: status.state,
+      ...(status.peerId ? { peerId: status.peerId } : {}),
+      routeHints: status.routeHints,
+      coordinationRelays: status.coordinationRelays,
+      profilePresent: profile.exists,
+      profileEnabled: profile.enabled,
+      clientAvailable: input.directPeerClientAvailable,
+      managementAvailable: true,
+    };
+  };
+
+  const peerManagementTarget = async (profileIdValue: unknown) => {
+    const target = await managedMutationTarget(profileIdValue);
+    const capability = await input.runServiceManagement({
+      destination: target.transport.destination,
+      ...(target.transport.sshPort === undefined
+        ? {}
+        : { sshPort: target.transport.sshPort }),
+      operatorPath: target.managed.service.operatorPath,
+      action: 'status',
+      expectedTarget: target.expectedTarget,
+      capabilityRequest: RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
+    });
+    if (capability.kind === 'error') throw new Error(capability.error.message);
+    if (capability.action !== 'status') {
+      throw new Error('Runtime Host returned an unrelated capability result');
+    }
+    return {
+      ...target,
+      available: capability.operatorCapabilities?.includes(
+        RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
+      ) === true,
+    };
+  };
+
+  const unavailablePeerSnapshot = async (
+    profileId: string,
+  ): Promise<DesktopRuntimeHostDirectPeerSnapshot> => {
+    const profile = await input.profiles.resolveManagedDirectPeerProfile(profileId);
+    return {
+      state: 'unsupported',
+      routeHints: [],
+      coordinationRelays: [],
+      profilePresent: profile.exists,
+      profileEnabled: profile.enabled,
+      clientAvailable: input.directPeerClientAvailable,
+      managementAvailable: false,
+    };
+  };
+
+  const getDirectPeer = async (
+    profileIdValue: unknown,
+  ): Promise<DesktopRuntimeHostDirectPeerSnapshot> => {
+    const { profileId, managed, transport, expectedTarget, available } =
+      await peerManagementTarget(profileIdValue);
+    if (!available) return unavailablePeerSnapshot(profileId);
+    const response = await input.runPeerManagement({
+      destination: transport.destination,
+      ...(transport.sshPort === undefined ? {} : { sshPort: transport.sshPort }),
+      operatorPath: managed.service.operatorPath,
+      action: 'status',
+      expectedTarget,
+    });
+    if (response.kind !== 'result') {
+      throw new Error(
+        response.kind === 'error'
+          ? response.error.message
+          : 'Runtime Host returned an unrelated direct-peer result',
+      );
+    }
+    return peerSnapshot(profileId, response.status);
+  };
+
+  const configureDirectPeer = async (
+    profileIdValue: unknown,
+    enabledValue: unknown,
+    coordinationRelaysValue: unknown,
+  ): Promise<DesktopRuntimeHostDirectPeerSnapshot> => {
+    if (typeof enabledValue !== 'boolean') {
+      throw new Error('Runtime Host direct-peer state is invalid');
+    }
+    const coordinationRelays = requireCoordinationRelays(coordinationRelaysValue);
+    const { profileId, managed, transport, expectedTarget, available } =
+      await peerManagementTarget(profileIdValue);
+    if (!available) {
+      throw new Error('Update this Runtime Host before managing Direct peer access');
+    }
+    const peerProfile = await input.profiles.resolveManagedDirectPeerProfile(profileId);
+    if (peerProfile.enabled) {
+      throw new Error('Disable the Direct peer profile before changing its listener');
+    }
+    const response = await input.runPeerManagement({
+      destination: transport.destination,
+      ...(transport.sshPort === undefined ? {} : { sshPort: transport.sshPort }),
+      operatorPath: managed.service.operatorPath,
+      action: enabledValue ? 'enable' : 'disable',
+      ...(enabledValue ? { coordinationRelays } : {}),
+      expectedTarget,
+    });
+    if (response.kind !== 'result') {
+      throw new Error(
+        response.kind === 'error'
+          ? response.error.message
+          : 'Runtime Host returned an unrelated direct-peer result',
+      );
+    }
+    const status = response.status;
+    if (enabledValue) {
+      try {
+        if (
+          status.state !== 'enabled' ||
+          !status.peerId ||
+          status.routeHints.length === 0 && status.coordinationRelays.length === 0
+        ) {
+          throw new Error('Runtime Host did not return a usable direct-peer descriptor');
+        }
+        await input.profiles.upsertManagedDirectPeerProfile(profileId, {
+          peerId: status.peerId,
+          routeHints: status.routeHints,
+          coordinationRelays: status.coordinationRelays,
+        });
+      } catch (failure) {
+        try {
+          const rollback = await input.runPeerManagement({
+            destination: transport.destination,
+            ...(transport.sshPort === undefined ? {} : { sshPort: transport.sshPort }),
+            operatorPath: managed.service.operatorPath,
+            action: 'disable',
+            expectedTarget,
+          });
+          if (rollback.kind !== 'result' || rollback.status.state === 'enabled') {
+            throw new Error(
+              rollback.kind === 'error'
+                ? rollback.error.message
+                : 'Runtime Host did not confirm that Direct peer access was disabled',
+            );
+          }
+        } catch (rollbackFailure) {
+          throw new AggregateError(
+            [asError(failure), asError(rollbackFailure)],
+            'Direct peer setup failed and its listener may still be enabled',
+          );
+        }
+        throw failure;
+      }
+    } else {
+      await input.profiles.removeManagedDirectPeerProfile(profileId);
+    }
+    return peerSnapshot(profileId, status);
+  };
+
   const update = async (
     profileIdValue: unknown,
     allowInterruptActiveTasksValue: unknown,
@@ -574,6 +743,8 @@ export function createDesktopRuntimeHostManagement(input: {
     getUpdatePolicy: 'runtime-host-management:get-update-policy',
     setUpdatePolicy: 'runtime-host-management:set-update-policy',
     reconcileUpdate: 'runtime-host-management:reconcile-update',
+    getDirectPeer: 'runtime-host-management:get-direct-peer',
+    configureDirectPeer: 'runtime-host-management:configure-direct-peer',
   } as const;
   input.ipcMain.handle(channels.run, (_event, profileId: unknown, action: unknown) =>
     run(profileId, action));
@@ -613,6 +784,13 @@ export function createDesktopRuntimeHostManagement(input: {
     updatePolicy(profileId, policy));
   input.ipcMain.handle(channels.reconcileUpdate, (_event, profileId: unknown) =>
     reconcileUpdate(profileId));
+  input.ipcMain.handle(channels.getDirectPeer, (_event, profileId: unknown) =>
+    getDirectPeer(profileId));
+  input.ipcMain.handle(
+    channels.configureDirectPeer,
+    (_event, profileId: unknown, enabled: unknown, coordinationRelays: unknown) =>
+      configureDirectPeer(profileId, enabled, coordinationRelays),
+  );
 
   return {
     close() {
@@ -621,6 +799,28 @@ export function createDesktopRuntimeHostManagement(input: {
   };
 }
 
+function asError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value));
+}
+
+function requireCoordinationRelays(value: unknown): readonly string[] {
+  if (
+    !Array.isArray(value) ||
+    value.length > 16 ||
+    value.some(
+      (relay) =>
+        typeof relay !== 'string' ||
+        relay.length === 0 ||
+        Buffer.byteLength(relay, 'utf8') > 2 * 1024 ||
+        /[\s\u0000-\u001f\u007f]/u.test(relay),
+    ) ||
+    new Set(value).size !== value.length
+  ) {
+    throw new Error('Runtime Host coordination relay list is invalid');
+  }
+  return value;
+}
+
 function projectUpdatePolicy(
   frame: Extract<RuntimeHostServiceManagementFrame, {
     readonly kind: 'result';
diff --git a/apps/desktop/src/main/runtime-host-peer-client.ts b/apps/desktop/src/main/runtime-host-peer-client.ts
new file mode 100644
index 000000000..395e194f9
--- /dev/null
+++ b/apps/desktop/src/main/runtime-host-peer-client.ts
@@ -0,0 +1,59 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const NATIVE_FILE = 'maka_runtime_host_peer.node';
+
+export async function configureDesktopRuntimeHostPeerClient(input: {
+  readonly isPackaged: boolean;
+  readonly appPath: string;
+  readonly resourcesPath: string;
+  readonly clientDataRoot: string;
+  readonly environment?: NodeJS.ProcessEnv;
+}): Promise<boolean> {
+  const environment = input.environment ?? process.env;
+  const explicitNativePath = environment.MAKA_RUNTIME_HOST_PEER_NATIVE_PATH?.trim();
+  const explicitKeyPath = environment.MAKA_RUNTIME_HOST_PEER_KEY_PATH?.trim();
+  if (explicitNativePath || explicitKeyPath) return Boolean(explicitNativePath && explicitKeyPath);
+  const nativePath = input.isPackaged
+    ? join(input.resourcesPath, 'runtime-host-peer', NATIVE_FILE)
+    : join(
+        input.appPath,
+        '..',
+        '..',
+        'native',
+        'runtime-host-peer',
+        'target',
+        'release',
+        NATIVE_FILE,
+      );
+  try {
+    await access(nativePath);
+  } catch {
+    return false;
+  }
+  environment.MAKA_RUNTIME_HOST_PEER_NATIVE_PATH = nativePath;
+  environment.MAKA_RUNTIME_HOST_PEER_KEY_PATH = join(
+    input.clientDataRoot,
+    'runtime-host-client.peer.key',
+  );
+  return true;
+}
diff --git a/apps/desktop/src/main/runtime-host-profile-service.ts b/apps/desktop/src/main/runtime-host-profile-service.ts
index 92c9aff15..5688823e0 100644
--- a/apps/desktop/src/main/runtime-host-profile-service.ts
+++ b/apps/desktop/src/main/runtime-host-profile-service.ts
@@ -17,7 +17,7 @@
  * under the License.
  */
 
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { open, readFile, rename, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import {
@@ -99,6 +99,19 @@ export interface DesktopRuntimeHostProfileService {
   resolveManagedAccess(
     profileId: string,
   ): Promise<DesktopRuntimeHostManagedAccess | undefined>;
+  resolveManagedDirectPeerProfile(profileId: string): Promise<{
+    readonly exists: boolean;
+    readonly enabled: boolean;
+  }>;
+  upsertManagedDirectPeerProfile(
+    profileId: string,
+    peer: {
+      readonly peerId: string;
+      readonly routeHints: readonly string[];
+      readonly coordinationRelays: readonly string[];
+    },
+  ): Promise<void>;
+  removeManagedDirectPeerProfile(profileId: string): Promise<void>;
   clearManagedServiceBinding(expected: DesktopRuntimeHostManagedServiceBinding): Promise<void>;
   markManagedServiceUninstalling(
     expected: DesktopRuntimeHostManagedServiceBinding,
@@ -370,25 +383,65 @@ export function createDesktopRuntimeHostProfileService(input: {
     preferences = next;
   };
 
+  const resolveActivationTarget = async (
+    target: ResolvedRuntimeHostProfile,
+  ): Promise<ResolvedRuntimeHostProfile> => {
+    if (
+      target.profile.kind !== 'remote' ||
+      target.profile.transport.kind !== 'libp2p-direct'
+    ) {
+      return target;
+    }
+    const directProfile = target.profile;
+    const document = await catalog.read();
+    const sourceProfile = document.profiles.find(
+      (profile) =>
+        profile.kind === 'remote' &&
+        profile.transport.kind === 'ssh' &&
+        profile.rootId === directProfile.rootId &&
+        managedDirectPeerProfileId(profile.id) === directProfile.id,
+    );
+    if (!sourceProfile) return target;
+    const managed = findDesktopRuntimeHostManagedServiceBinding(
+      await managedServices.read(),
+      sourceProfile,
+    );
+    if (!managed) return target;
+    if (managed.state !== 'active') {
+      throw new Error('The managed SSH recovery profile is not available');
+    }
+    const source = await catalog.resolve(sourceProfile.id);
+    if (source.profile.kind !== 'remote' || !source.credential) {
+      throw new Error('The managed SSH recovery profile credential is not available');
+    }
+    if (source.credential === target.credential) return target;
+    const rebound = await catalog.rebindIfCurrent(target, target.profile, source.credential);
+    if (!rebound.rebound) {
+      throw new Error('The Direct peer profile changed before its credential could be refreshed');
+    }
+    return catalog.resolve(target.profile.id);
+  };
+
   const activateTarget = async (
     target: ResolvedRuntimeHostProfile,
     sshInteraction: "terminal" | "batch",
   ): Promise<void> => {
     try {
-      await input.enable(target, sshInteraction);
-      const current = await catalog.resolve(target.profile.id).catch(() => undefined);
-      if (!current || !sameResolvedRuntimeHostProfileTarget(current, target)) {
-        await input.disable(target.profile.id);
+      const activationTarget = await resolveActivationTarget(target);
+      await input.enable(activationTarget, sshInteraction);
+      const current = await catalog.resolve(activationTarget.profile.id).catch(() => undefined);
+      if (!current || !sameResolvedRuntimeHostProfileTarget(current, activationTarget)) {
+        await input.disable(activationTarget.profile.id);
         throw new Error("Runtime Host profile changed while it was connecting");
       }
       const remainsEnabled =
-        target.profile.id === preferences.defaultProfileId ||
-        preferences.enabledRemoteProfileIds.includes(target.profile.id);
+        activationTarget.profile.id === preferences.defaultProfileId ||
+        preferences.enabledRemoteProfileIds.includes(activationTarget.profile.id);
       if (!remainsEnabled) {
-        await input.disable(target.profile.id);
+        await input.disable(activationTarget.profile.id);
         return;
       }
-      unavailable.delete(target.profile.id);
+      unavailable.delete(activationTarget.profile.id);
     } catch (error) {
       const failure = asError(error);
       unavailable.set(target.profile.id, failure);
@@ -752,15 +805,115 @@ export function createDesktopRuntimeHostProfileService(input: {
           : undefined;
       });
     },
+    resolveManagedDirectPeerProfile(profileId) {
+      return mutate(async () => {
+        const peerProfileId = managedDirectPeerProfileId(profileId);
+        return {
+          exists: (await catalog.read()).profiles.some((profile) => profile.id === peerProfileId),
+          enabled: preferences.enabledRemoteProfileIds.includes(peerProfileId),
+        };
+      });
+    },
+    upsertManagedDirectPeerProfile(profileId, peer) {
+      return mutateProfiles(async () => {
+        assertPairingComplete(profileId);
+        const source = await catalog.resolve(profileId);
+        if (
+          source.profile.kind !== 'remote' ||
+          source.profile.transport.kind !== 'ssh' ||
+          !source.credential
+        ) {
+          throw new Error('Direct peer can only be added through a managed SSH Runtime Host');
+        }
+        const managed = findDesktopRuntimeHostManagedServiceBinding(
+          await managedServices.read(),
+          source.profile,
+        );
+        if (!managed || managed.state !== 'active') {
+          throw new Error('This Runtime Host profile is not bound to an active managed service');
+        }
+        if (peer.routeHints.length === 0 && peer.coordinationRelays.length === 0) {
+          throw new Error('Runtime Host returned an invalid direct-peer descriptor');
+        }
+        const peerProfileId = managedDirectPeerProfileId(profileId);
+        if (preferences.enabledRemoteProfileIds.includes(peerProfileId)) {
+          throw new Error('Disable the Direct peer profile before changing its listener');
+        }
+        const profile: RemoteRuntimeHostProfile = {
+          id: peerProfileId,
+          name: directPeerProfileName(source.profile.name),
+          kind: 'remote',
+          rootId: source.profile.rootId,
+          transport: {
+            kind: 'libp2p-direct',
+            peerId: peer.peerId,
+            routeHints: peer.routeHints,
+            coordinationRelays: peer.coordinationRelays,
+          },
+        };
+        const existing = (await catalog.read()).profiles.find(
+          (candidate) => candidate.id === peerProfileId,
+        );
+        if (!existing) {
+          await catalog.create(profile, source.credential);
+          return;
+        }
+        const previous = await catalog.resolve(peerProfileId);
+        if (previous.profile.kind !== 'remote' || previous.profile.rootId !== source.profile.rootId) {
+          throw new Error('The Direct peer profile identity is already in use');
+        }
+        const rebound = await catalog.rebindIfCurrent(previous, profile, source.credential);
+        if (!rebound.rebound) {
+          throw new Error('The Direct peer profile changed before it could be updated');
+        }
+      });
+    },
+    removeManagedDirectPeerProfile(profileId) {
+      return mutateProfiles(async () => {
+        assertPairingComplete(profileId);
+        const peerProfileId = managedDirectPeerProfileId(profileId);
+        if (preferences.enabledRemoteProfileIds.includes(peerProfileId)) {
+          throw new Error('Disable the Direct peer profile before changing its listener');
+        }
+        const current = await catalog.resolve(peerProfileId).catch(() => undefined);
+        if (!current) return;
+        const source = await catalog.resolve(profileId);
+        if (
+          source.profile.kind !== 'remote' ||
+          source.profile.transport.kind !== 'ssh' ||
+          current.profile.kind !== 'remote' ||
+          current.profile.transport.kind !== 'libp2p-direct' ||
+          current.profile.rootId !== source.profile.rootId
+        ) {
+          throw new Error('The Direct peer profile identity is already in use');
+        }
+        const removed = await catalog.removeIfCurrent(current);
+        if (!removed.removed) {
+          throw new Error('The Direct peer profile changed before it could be removed');
+        }
+      });
+    },
     markManagedServiceUninstalling(expected) {
       return mutateProfiles(async () => {
         assertPairingComplete(expected.profile.id);
-        const current = (await catalog.read()).profiles.find(
+        const document = await catalog.read();
+        const current = document.profiles.find(
           (profile) => profile.id === expected.profile.id,
         );
         if (
           !current ||
-          !sameRemoteRuntimeHostProfileTarget(current, expected.profile) ||
+          !sameRemoteRuntimeHostProfileTarget(current, expected.profile)
+        ) {
+          throw new Error('Runtime Host managed service binding changed during uninstall');
+        }
+        if (
+          document.profiles.some(
+            (profile) => profile.id === managedDirectPeerProfileId(expected.profile.id),
+          )
+        ) {
+          throw new Error('Disable and remove the Direct peer profile before uninstalling this service');
+        }
+        if (
           !(await managedServices.markUninstallingIfCurrent(
             expected.profile,
             expected.service,
@@ -916,10 +1069,20 @@ export function createDesktopRuntimeHostProfileService(input: {
         if (preferences.defaultProfileId === profileId) {
           throw new Error("Choose another default Runtime Host before removing this one");
         }
-        const profile = (await catalog.read()).profiles.find(
+        const document = await catalog.read();
+        const profile = document.profiles.find(
           (candidate) => candidate.id === profileId,
         );
         if (!profile) throw new Error("Runtime Host profile was not found");
+        if (
+          profile.kind === 'remote' &&
+          profile.transport.kind === 'ssh' &&
+          document.profiles.some(
+            (candidate) => candidate.id === managedDirectPeerProfileId(profileId),
+          )
+        ) {
+          throw new Error('Disable and remove the Direct peer profile before removing its SSH profile');
+        }
         const managedBinding = findDesktopRuntimeHostManagedServiceBinding(
           await managedServices.read(),
           profile,
@@ -942,6 +1105,18 @@ export function createDesktopRuntimeHostProfileService(input: {
   };
 }
 
+function managedDirectPeerProfileId(sourceProfileId: string): string {
+  const digest = createHash('sha256').update(sourceProfileId).digest('hex').slice(0, 32);
+  return `direct-${digest}`;
+}
+
+function directPeerProfileName(sourceName: string): string {
+  const suffix = ' · Direct';
+  let name = sourceName;
+  while (Buffer.byteLength(name + suffix, 'utf8') > 128) name = name.slice(0, -1);
+  return `${name}${suffix}`;
+}
+
 async function rollbackCreatedProfile(
   catalog: RuntimeHostProfileCatalog,
   target: ResolvedRuntimeHostProfile,
diff --git a/apps/desktop/src/main/runtime-host-ssh-terminal.ts b/apps/desktop/src/main/runtime-host-ssh-terminal.ts
index beaca6e0c..6e7f05db8 100644
--- a/apps/desktop/src/main/runtime-host-ssh-terminal.ts
+++ b/apps/desktop/src/main/runtime-host-ssh-terminal.ts
@@ -35,6 +35,7 @@ import {
 } from '@maka/runtime-host/client';
 import {
   decodeRuntimeHostAccessManagementFrame,
+  decodeRuntimeHostPeerManagementFrame,
   decodeRuntimeHostServiceManagementFrame,
   decodeRuntimeHostSetupFrame,
   RUNTIME_HOST_ACCESS_MANAGEMENT_FRAME_PREFIX,
@@ -42,10 +43,14 @@ import {
   RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV,
   RUNTIME_HOST_OPERATOR_PROJECT_DIRECTORY_CONFIGURATION_REQUEST_ENV,
   RUNTIME_HOST_OPERATOR_UPDATE_SCHEDULER_CAPABILITY,
+  RUNTIME_HOST_PEER_MANAGEMENT_FRAME_PREFIX,
   RUNTIME_HOST_SERVICE_MANAGEMENT_FRAME_PREFIX,
   RUNTIME_HOST_SETUP_FRAME_PREFIX,
   type RuntimeHostAccessManagementFrame,
   type RuntimeHostManagedUpdatePolicy,
+  type RuntimeHostPeerManagementAction,
+  type RuntimeHostPeerManagementFrame,
+  type RuntimeHostOperatorCapability,
   type RuntimeHostServiceManagementAction,
   type RuntimeHostServiceManagementFrame,
   type RuntimeHostServiceUpdatePhase,
@@ -78,6 +83,7 @@ const TERMINAL_OUTPUT_MAX = 64 * 1024;
 const SETUP_FRAME_PENDING_MAX = 20 * 1024;
 const MANAGEMENT_FRAME_PENDING_MAX = 128 * 1024;
 const ACCESS_MANAGEMENT_FRAME_PENDING_MAX = 768 * 1024;
+const PEER_MANAGEMENT_FRAME_PENDING_MAX = 128 * 1024;
 const SETUP_TIMEOUT_MS = 10 * 60_000;
 const MANAGEMENT_TIMEOUT_MS = 2 * 60_000;
 const PROCESS_STOP_GRACE_MS = 2_000;
@@ -111,6 +117,7 @@ export interface DesktopRuntimeHostSshManagementInput {
   readonly expectedConfigFingerprint?: string;
   readonly allowInterruptActiveTasks?: boolean;
   readonly retainManagedDeployment?: boolean;
+  readonly capabilityRequest?: RuntimeHostOperatorCapability;
   readonly signal?: AbortSignal;
 }
 
@@ -140,6 +147,16 @@ export interface DesktopRuntimeHostSshUpdateReconciliationInput {
   readonly signal?: AbortSignal;
 }
 
+export interface DesktopRuntimeHostSshPeerManagementInput {
+  readonly destination: string;
+  readonly sshPort?: number;
+  readonly operatorPath: string;
+  readonly action: Extract<RuntimeHostPeerManagementAction, 'enable' | 'disable' | 'status'>;
+  readonly coordinationRelays?: readonly string[];
+  readonly expectedTarget: DesktopRuntimeHostSshManagementInput['expectedTarget'];
+  readonly signal?: AbortSignal;
+}
+
 export interface DesktopRuntimeHostSshCleanupInput {
   readonly destination: string;
   readonly sshPort?: number;
@@ -227,6 +244,9 @@ export function createDesktopRuntimeHostSshTerminal(input: {
   runAccessManagement(
     input: DesktopRuntimeHostSshAccessInput,
   ): Promise<RuntimeHostAccessManagementFrame>;
+  runPeerManagement(
+    input: DesktopRuntimeHostSshPeerManagementInput,
+  ): Promise<RuntimeHostPeerManagementFrame>;
   cleanupManagedDeployment(input: DesktopRuntimeHostSshCleanupInput): Promise<void>;
   close(): Promise<void>;
 } {
@@ -725,6 +745,17 @@ export function createDesktopRuntimeHostSshTerminal(input: {
         frameAction: (frame) => frame.action,
         label: 'Remote Runtime Host access management',
       }),
+    runPeerManagement: (peerInput) =>
+      runFramedManagement({
+        ...peerInput,
+        remoteCommand: runtimeHostPeerManagementRemoteCommand(peerInput),
+        prefix: RUNTIME_HOST_PEER_MANAGEMENT_FRAME_PREFIX,
+        pendingMaxBytes: PEER_MANAGEMENT_FRAME_PENDING_MAX,
+        decode: decodeRuntimeHostPeerManagementFrame,
+        action: peerInput.action,
+        frameAction: (frame) => frame.action,
+        label: 'Remote Runtime Host direct-peer management',
+      }),
     cleanupManagedDeployment: async (cleanupInput) => {
       if (closed) throw new Error('Runtime Host SSH terminal is closed');
       cleanupInput.signal?.throwIfAborted();
@@ -1097,7 +1128,7 @@ function runtimeHostServiceManagementRemoteCommand(
   const invocation =
     `${RUNTIME_HOST_OPERATOR_PROJECT_DIRECTORY_CONFIGURATION_REQUEST_ENV}=1 ` +
     `${RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV}=` +
-    `${quotePosix(RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY)} exec ${command}`;
+    `${quotePosix(input.capabilityRequest ?? RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY)} exec ${command}`;
   return `exec "\${SHELL:-/bin/sh}" -lic ${quotePosix(invocation)}`;
 }
 
@@ -1186,6 +1217,24 @@ function runtimeHostAccessManagementRemoteCommand(
   return `exec "\${SHELL:-/bin/sh}" -lic ${quotePosix(`exec ${command}`)}`;
 }
 
+function runtimeHostPeerManagementRemoteCommand(
+  input: DesktopRuntimeHostSshPeerManagementInput,
+): string {
+  const command = [
+    input.operatorPath,
+    'peer',
+    input.action,
+    '--framed',
+    ...(input.action === 'enable' && input.coordinationRelays
+      ? input.coordinationRelays.length === 0
+        ? ['--clear-coordination-relays']
+        : input.coordinationRelays.flatMap((relay) => ['--coordination-relay', relay])
+      : []),
+    ...managedServiceTargetArgs(input.expectedTarget),
+  ].map(quotePosix).join(' ');
+  return `exec "\${SHELL:-/bin/sh}" -lic ${quotePosix(`exec ${command}`)}`;
+}
+
 function runtimeHostManagedDeploymentCleanupRemoteCommand(
   input: DesktopRuntimeHostSshCleanupInput,
 ): string {
diff --git a/apps/desktop/src/preload/bridge-contract.d.ts b/apps/desktop/src/preload/bridge-contract.d.ts
index 1eb3a0e72..c8bf2aa37 100644
--- a/apps/desktop/src/preload/bridge-contract.d.ts
+++ b/apps/desktop/src/preload/bridge-contract.d.ts
@@ -471,6 +471,17 @@ export interface DesktopRuntimeHostManagementProgress {
     | import('@maka/runtime-host/operator').RuntimeHostServiceUpdatePhase;
 }
 
+export interface DesktopRuntimeHostDirectPeerSnapshot {
+  readonly state: 'unsupported' | 'not_configured' | 'disabled' | 'enabled';
+  readonly peerId?: string;
+  readonly routeHints: readonly string[];
+  readonly coordinationRelays: readonly string[];
+  readonly profilePresent: boolean;
+  readonly profileEnabled: boolean;
+  readonly clientAvailable: boolean;
+  readonly managementAvailable: boolean;
+}
+
 type RuntimeHostUpdatePolicyResult = Extract<
   RuntimeHostServiceManagementFrame,
   { kind: 'result'; action: 'update_policy' }
@@ -650,6 +661,12 @@ export interface MakaBridge {
       policy: import('@maka/runtime-host/operator').RuntimeHostManagedUpdatePolicy,
     ): Promise<DesktopRuntimeHostUpdatePolicySnapshot>;
     reconcileUpdate(profileId: string): Promise<DesktopRuntimeHostUpdateReconciliationResponse>;
+    getDirectPeer(profileId: string): Promise<DesktopRuntimeHostDirectPeerSnapshot>;
+    configureDirectPeer(
+      profileId: string,
+      enabled: boolean,
+      coordinationRelays: readonly string[],
+    ): Promise<DesktopRuntimeHostDirectPeerSnapshot>;
     listCredentials(profileId: string): Promise<DesktopRuntimeHostAccessSnapshot>;
     rotateCredential(profileId: string): Promise<DesktopRuntimeHostAccessSnapshot>;
     revokeCredential(
diff --git a/apps/desktop/src/preload/preload.ts b/apps/desktop/src/preload/preload.ts
index 45a6fc19c..22a583b09 100644
--- a/apps/desktop/src/preload/preload.ts
+++ b/apps/desktop/src/preload/preload.ts
@@ -1301,6 +1301,21 @@ const makaBridge = {
     reconcileUpdate(profileId: string) {
       return ipcRenderer.invoke('runtime-host-management:reconcile-update', profileId);
     },
+    getDirectPeer(profileId: string) {
+      return ipcRenderer.invoke('runtime-host-management:get-direct-peer', profileId);
+    },
+    configureDirectPeer(
+      profileId: string,
+      enabled: boolean,
+      coordinationRelays: readonly string[],
+    ) {
+      return ipcRenderer.invoke(
+        'runtime-host-management:configure-direct-peer',
+        profileId,
+        enabled,
+        coordinationRelays,
+      );
+    },
     listCredentials(profileId: string): Promise<DesktopRuntimeHostAccessSnapshot> {
       return ipcRenderer.invoke('runtime-host-management:list-credentials', profileId);
     },
diff --git a/apps/desktop/src/renderer/locales/settings-projects-copy.ts b/apps/desktop/src/renderer/locales/settings-projects-copy.ts
index b8667e7c5..64b22fc9c 100644
--- a/apps/desktop/src/renderer/locales/settings-projects-copy.ts
+++ b/apps/desktop/src/renderer/locales/settings-projects-copy.ts
@@ -75,12 +75,28 @@ export type SettingsProjectsCopy = {
     credentialHelp: string;
     saveAndEnable: string;
     defaultBadge: string;
+    experimentalBadge: string;
     defaultDisableHelp: string;
     unavailable: string;
     manage: string;
     managementTitle(name: string): string;
     serviceStatus: string;
     serviceState: Record<import('../../preload/bridge-contract.js').DesktopRuntimeHostManagementResult['service']['state'], string>;
+    directPeer: string;
+    directPeerDescription: string;
+    directPeerState: Record<'unsupported' | 'not_configured' | 'disabled' | 'enabled' | 'unavailable', string>;
+    directPeerUnavailable: string;
+    directPeerUpgradeRequired: string;
+    directPeerClientUnavailable: string;
+    directPeerDisableProfileFirst: string;
+    directPeerId: string;
+    directPeerRoutes: string;
+    directPeerCoordinationRelays: string;
+    directPeerCoordinationRelaysPlaceholder: string;
+    directPeerEnable: string;
+    directPeerDisable: string;
+    directPeerAddProfile: string;
+    directPeerActionFailed: string;
     installedVersion: string;
     operatingSystem: string;
     processId: string;
@@ -291,6 +307,7 @@ const SETTINGS_PROJECTS_COPY_BY_LOCALE = {
       credentialHelp: '在远程机器使用 desktop-client preset 签发',
       saveAndEnable: '保存并启用',
       defaultBadge: '默认',
+      experimentalBadge: '实验性',
       defaultDisableHelp: '先选择另一个默认 Host,才能停用此 Host',
       unavailable: '无法连接',
       manage: '管理',
@@ -303,6 +320,27 @@ const SETTINGS_PROJECTS_COPY_BY_LOCALE = {
         running: '运行中',
         failed: '启动失败',
       },
+      directPeer: 'Direct peer(实验性)',
+      directPeerDescription: '创建独立的实验性 Direct profile。受限 NAT 或被阻止的 UDP 可能使其不可达,且不会自动回退;保留 SSH profile 用于手动恢复。',
+      directPeerState: {
+        unsupported: '需要更新',
+        not_configured: '未配置',
+        disabled: '已停用',
+        enabled: '已启用',
+        unavailable: '不可用',
+      },
+      directPeerUnavailable: '无法读取 Direct peer 状态',
+      directPeerUpgradeRequired: '请先更新远程 Runtime Host,再管理 Direct peer。',
+      directPeerClientUnavailable: '当前 Desktop 构建不包含 Direct peer 支持。',
+      directPeerDisableProfileFirst: '请先在 Runtime Host 列表中停用 Direct peer。',
+      directPeerId: 'Peer ID',
+      directPeerRoutes: '可用路径',
+      directPeerCoordinationRelays: '连接协调节点(可选)',
+      directPeerCoordinationRelaysPlaceholder: '多个地址用逗号分隔',
+      directPeerEnable: '启用并添加',
+      directPeerDisable: '停用',
+      directPeerAddProfile: '添加到 Desktop',
+      directPeerActionFailed: 'Direct peer 操作失败',
       installedVersion: '版本',
       operatingSystem: '系统',
       processId: '进程 ID',
@@ -513,6 +551,7 @@ const SETTINGS_PROJECTS_COPY_BY_LOCALE = {
       credentialHelp: 'Issue it on the remote machine with the desktop-client preset',
       saveAndEnable: 'Save and enable',
       defaultBadge: 'Default',
+      experimentalBadge: 'Experimental',
       defaultDisableHelp: 'Choose another default Host before disabling this Host',
       unavailable: 'Unavailable',
       manage: 'Manage',
@@ -525,6 +564,27 @@ const SETTINGS_PROJECTS_COPY_BY_LOCALE = {
         running: 'Running',
         failed: 'Failed',
       },
+      directPeer: 'Direct peer (experimental)',
+      directPeerDescription: 'Create an independent experimental Direct profile. Restrictive NAT or blocked UDP may make it unreachable, and it does not fall back automatically; keep the SSH profile for manual recovery.',
+      directPeerState: {
+        unsupported: 'Update required',
+        not_configured: 'Not configured',
+        disabled: 'Disabled',
+        enabled: 'Enabled',
+        unavailable: 'Unavailable',
+      },
+      directPeerUnavailable: 'Direct peer status is unavailable',
+      directPeerUpgradeRequired: 'Update the remote Runtime Host before managing Direct peer.',
+      directPeerClientUnavailable: 'This Desktop build does not include Direct peer support.',
+      directPeerDisableProfileFirst: 'Disable the Direct peer in the Runtime Host list first.',
+      directPeerId: 'Peer ID',
+      directPeerRoutes: 'Routes',
+      directPeerCoordinationRelays: 'Connection coordination peers (optional)',
+      directPeerCoordinationRelaysPlaceholder: 'Separate multiple addresses with commas',
+      directPeerEnable: 'Enable and add',
+      directPeerDisable: 'Disable',
+      directPeerAddProfile: 'Add to Desktop',
+      directPeerActionFailed: 'Direct peer action failed',
       installedVersion: 'Version',
       operatingSystem: 'System',
       processId: 'Process ID',
diff --git a/apps/desktop/src/renderer/settings/runtime-host-management-dialog.tsx b/apps/desktop/src/renderer/settings/runtime-host-management-dialog.tsx
index 3632c4876..95585c395 100644
--- a/apps/desktop/src/renderer/settings/runtime-host-management-dialog.tsx
+++ b/apps/desktop/src/renderer/settings/runtime-host-management-dialog.tsx
@@ -36,6 +36,7 @@ import { uiLocaleToIntlLocale, type UiLocale } from '@maka/core/ui-locale';
 import type { RemoteRuntimeHostProfile } from '@maka/runtime-host/client';
 import type {
   DesktopRuntimeHostManagementAction,
+  DesktopRuntimeHostDirectPeerSnapshot,
   DesktopRuntimeHostManagementResult,
   DesktopRuntimeHostManagementProgress,
   DesktopRuntimeHostAccessCredential,
@@ -97,6 +98,9 @@ export function RuntimeHostManagementDialog(props: {
   const [lastUpdateOutcome, setLastUpdateOutcome] =
     useState<DesktopRuntimeHostUpdateReconciliationOutcome>();
   const [directoryPolicyEdit, setDirectoryPolicyEdit] = useState<DirectoryPolicyEdit>();
+  const [directPeer, setDirectPeer] = useState<DesktopRuntimeHostDirectPeerSnapshot>();
+  const [directPeerError, setDirectPeerError] = useState<string>();
+  const [coordinationRelays, setCoordinationRelays] = useState('');
   const nextDirectoryRootId = useRef(1);
   const logsRef = useRef<HTMLPreElement>(null);
 
@@ -117,6 +121,9 @@ export function RuntimeHostManagementDialog(props: {
     setUpdatePolicyError(undefined);
     setLastUpdateOutcome(undefined);
     setDirectoryPolicyEdit(undefined);
+    setDirectPeer(undefined);
+    setDirectPeerError(undefined);
+    setCoordinationRelays('');
     setLoading(true);
     void (async () => {
       let shouldLoadUpdatePolicy = false;
@@ -144,6 +151,14 @@ export function RuntimeHostManagementDialog(props: {
           }
         }
       }
+      if (shouldLoadUpdatePolicy) {
+        try {
+          const peer = await window.maka.runtimeHostManagement.getDirectPeer(profile.id);
+          if (!disposed) applyDirectPeer(peer);
+        } catch (failure) {
+          if (!disposed) setDirectPeerError(settingsActionErrorMessage(failure, locale));
+        }
+      }
       if (!disposed) setLoading(false);
     })();
     return () => {
@@ -195,6 +210,55 @@ export function RuntimeHostManagementDialog(props: {
     }
   }
 
+  function applyDirectPeer(snapshot: DesktopRuntimeHostDirectPeerSnapshot): void {
+    setDirectPeer(snapshot);
+    setCoordinationRelays(snapshot.coordinationRelays.join(', '));
+    setDirectPeerError(undefined);
+  }
+
+  async function reloadDirectPeer(): Promise<void> {
+    if (!profile) return;
+    setLoading(true);
+    setDirectPeerError(undefined);
+    try {
+      applyDirectPeer(await window.maka.runtimeHostManagement.getDirectPeer(profile.id));
+    } catch (failure) {
+      setDirectPeerError(settingsActionErrorMessage(failure, locale));
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function configureDirectPeer(enabled: boolean): Promise<void> {
+    if (!profile) return;
+    setLoading(true);
+    setDirectPeerError(undefined);
+    try {
+      const relays = coordinationRelays
+        .split(',')
+        .map((relay) => relay.trim())
+        .filter(Boolean);
+      applyDirectPeer(
+        await window.maka.runtimeHostManagement.configureDirectPeer(
+          profile.id,
+          enabled,
+          relays,
+        ),
+      );
+    } catch (failure) {
+      const message = settingsActionErrorMessage(failure, locale);
+      try {
+        applyDirectPeer(await window.maka.runtimeHostManagement.getDirectPeer(profile.id));
+      } catch {
+        // Preserve the last authoritative snapshot when recovery cannot be read.
+      }
+      setDirectPeerError(message);
+      toast.error(copy.directPeerActionFailed, message);
+    } finally {
+      setLoading(false);
+    }
+  }
+
   async function loadAccess(): Promise<void> {
     if (!profile) return;
     setLoading(true);
@@ -607,6 +671,119 @@ export function RuntimeHostManagementDialog(props: {
                       <Fact label={copy.stateRoot} value={service.stateRoot} wide />
                     ) : null}
                   </dl>
+                  {serviceInstalled ? (
+                    <section className="settingsRuntimeHostDirectPeer">
+                      <div className="settingsRuntimeHostUpdatePolicyHeading">
+                        <div>
+                          <Text type="body" weight="semibold">{copy.directPeer}</Text>
+                          <Text type="supporting" color="secondary">
+                            {copy.directPeerDescription}
+                          </Text>
+                        </div>
+                        <Badge
+                          variant={directPeer?.state === 'enabled' ? 'success' : 'neutral'}
+                          label={directPeer
+                            ? copy.directPeerState[directPeer.state]
+                            : copy.directPeerState.unavailable}
+                        />
+                      </div>
+                      {directPeerError ? (
+                        <Banner
+                          status="warning"
+                          title={copy.directPeerUnavailable}
+                          description={directPeerError}
+                        />
+                      ) : null}
+                      {directPeer && !directPeer.managementAvailable ? (
+                        <Banner
+                          status="warning"
+                          title={copy.directPeerUpgradeRequired}
+                        />
+                      ) : null}
+                      {!directPeer ? (
+                        <div className="settingsRuntimeHostUpdatePolicyActions">
+                          <Button
+                            variant="secondary"
+                            size="sm"
+                            label={copy.refresh}
+                            isDisabled={loading}
+                            onClick={() => void reloadDirectPeer()}
+                          />
+                        </div>
+                      ) : null}
+                      {directPeer && !directPeer.clientAvailable ? (
+                        <Banner status="warning" title={copy.directPeerClientUnavailable} />
+                      ) : null}
+                      {directPeer?.profileEnabled ? (
+                        <Banner status="info" title={copy.directPeerDisableProfileFirst} />
+                      ) : null}
+                      {directPeer?.managementAvailable ? (
+                        <>
+                          {directPeer.peerId ? (
+                            <dl className="settingsRuntimeHostManagementFacts">
+                              <Fact label={copy.directPeerId} value={directPeer.peerId} wide />
+                              <Fact
+                                label={copy.directPeerRoutes}
+                                value={directPeer.routeHints.join(', ') || '—'}
+                                wide
+                              />
+                            </dl>
+                          ) : null}
+                          <TextInput
+                            label={copy.directPeerCoordinationRelays}
+                            value={coordinationRelays}
+                            placeholder={copy.directPeerCoordinationRelaysPlaceholder}
+                            isDisabled={
+                              loading ||
+                              directPeer.profileEnabled ||
+                              directPeer.state === 'enabled'
+                            }
+                            onChange={setCoordinationRelays}
+                          />
+                          <div className="settingsRuntimeHostUpdatePolicyActions">
+                            <Button
+                              variant="secondary"
+                              size="sm"
+                              label={copy.refresh}
+                              isDisabled={loading}
+                              onClick={() => void reloadDirectPeer()}
+                            />
+                            {directPeer.state === 'enabled' && !directPeer.profilePresent ? (
+                              <Button
+                                variant="secondary"
+                                size="sm"
+                                label={copy.directPeerAddProfile}
+                                isDisabled={
+                                  loading ||
+                                  directPeer.profileEnabled ||
+                                  !directPeer.clientAvailable
+                                }
+                                onClick={() => void configureDirectPeer(true)}
+                              />
+                            ) : null}
+                            <Button
+                              variant={directPeer.state === 'enabled' ? 'secondary' : 'primary'}
+                              size="sm"
+                              label={directPeer.state === 'enabled'
+                                ? copy.directPeerDisable
+                                : copy.directPeerEnable}
+                              isDisabled={
+                                loading ||
+                                directPeer.profileEnabled ||
+                                (
+                                  !directPeer.clientAvailable &&
+                                  directPeer.state !== 'enabled'
+                                )
+                              }
+                              onClick={() => void configureDirectPeer(
+                                directPeer.state !== 'enabled',
+                              )}
+                            />
+                          </div>
+                        </>
+                      ) : null}
+                    </section>
+                  ) : null}
                   {serviceInstalled ? (
                     <section className="settingsRuntimeHostUpdatePolicy">
                       <div className="settingsRuntimeHostUpdatePolicyHeading">
diff --git a/apps/desktop/src/renderer/settings/runtime-host-profiles-section.tsx b/apps/desktop/src/renderer/settings/runtime-host-profiles-section.tsx
index f66e7a32e..8d1b30578 100644
--- a/apps/desktop/src/renderer/settings/runtime-host-profiles-section.tsx
+++ b/apps/desktop/src/renderer/settings/runtime-host-profiles-section.tsx
@@ -390,49 +390,56 @@ export function RuntimeHostProfilesSection(props: {
                 <ListItem
                   key={profile.id}
                   label={profile.name}
-                description={
-                  profile.transport.kind === "ssh"
-                    ? profile.transport.destination
-                    : profile.transport.kind === "libp2p-direct"
-                      ? profile.transport.peerId
-                      : profile.transport.url
-                }
-                startContent={<Cpu size={ICON_SIZE.control} aria-hidden="true" />}
-                endContent={
-                  <HStack gap={2} align="center">
-                    {entry.isDefault ? <Badge variant="neutral" label={copy.defaultBadge} /> : null}
-                    {entry.readiness === "unavailable" ? <Badge variant="neutral" label={copy.unavailable} /> : null}
-                    <Switch
-                      label={profile.name}
-                      isLabelHidden
-                      value={entry.enabled}
-                      isDisabled={switching || entry.isDefault}
-                      disabledMessage={entry.isDefault ? copy.defaultDisableHelp : undefined}
-                      onChange={(enabled) => void setEnabled(profile.id, enabled)}
-                    />
-                    <MoreMenu
-                      label={copy.moreActions(profile.name)}
-                      size="sm"
-                      items={[
-                        ...(profile.transport.kind === "ssh" && entry.managedService
-                          ? [{
-                              label: copy.manage,
-                              isDisabled: switching,
-                              onClick: () => setManagedProfile(profile),
-                            }]
-                          : []),
-                        {
-                          label: copy.remove,
-                          isDisabled:
-                            switching ||
-                            entry.enabled ||
-                            entry.isDefault,
-                          onClick: () => void remove(profile.id),
-                        },
-                      ]}
-                    />
-                  </HStack>
-                }
+                  description={
+                    profile.transport.kind === "ssh"
+                      ? profile.transport.destination
+                      : profile.transport.kind === "libp2p-direct"
+                        ? abbreviatePeerId(profile.transport.peerId)
+                        : profile.transport.url
+                  }
+                  startContent={<Cpu size={ICON_SIZE.control} aria-hidden="true" />}
+                  endContent={
+                    <HStack gap={2} align="center">
+                      {entry.isDefault ? (
+                        <Badge variant="neutral" label={copy.defaultBadge} />
+                      ) : null}
+                      {profile.transport.kind === 'libp2p-direct' ? (
+                        <Badge variant="warning" label={copy.experimentalBadge} />
+                      ) : null}
+                      {entry.readiness === "unavailable" ? (
+                        <Badge variant="neutral" label={copy.unavailable} />
+                      ) : null}
+                      <Switch
+                        label={profile.name}
+                        isLabelHidden
+                        value={entry.enabled}
+                        isDisabled={switching || entry.isDefault}
+                        disabledMessage={entry.isDefault ? copy.defaultDisableHelp : undefined}
+                        onChange={(enabled) => void setEnabled(profile.id, enabled)}
+                      />
+                      <MoreMenu
+                        label={copy.moreActions(profile.name)}
+                        size="sm"
+                        items={[
+                          ...(profile.transport.kind === "ssh" && entry.managedService
+                            ? [{
+                                label: copy.manage,
+                                isDisabled: switching,
+                                onClick: () => setManagedProfile(profile),
+                              }]
+                            : []),
+                          {
+                            label: copy.remove,
+                            isDisabled:
+                              switching ||
+                              entry.enabled ||
+                              entry.isDefault,
+                            onClick: () => void remove(profile.id),
+                          },
+                        ]}
+                      />
+                    </HStack>
+                  }
                 />
               );
             })}
@@ -459,6 +466,10 @@ export function RuntimeHostProfilesSection(props: {
   );
 }
 
+function abbreviatePeerId(peerId: string): string {
+  return peerId.length <= 20 ? peerId : `${peerId.slice(0, 10)}…${peerId.slice(-6)}`;
+}
+
 function createTransport(draft: ReturnType<typeof createRemoteHostDraft>): RuntimeHostRemoteTransport {
   if (draft.transportKind === "tls") return { kind: "tls", url: draft.url };
   if (draft.transportKind === "plaintext") {
diff --git a/apps/desktop/src/renderer/styles/settings/runtime-host.css b/apps/desktop/src/renderer/styles/settings/runtime-host.css
index f0e7db6ce..a05e7b8d0 100644
--- a/apps/desktop/src/renderer/styles/settings/runtime-host.css
+++ b/apps/desktop/src/renderer/styles/settings/runtime-host.css
@@ -148,7 +148,8 @@
   gap: var(--space-2);
 }
 
-.settingsRuntimeHostUpdatePolicy {
+.settingsRuntimeHostUpdatePolicy,
+.settingsRuntimeHostDirectPeer {
   display: grid;
   gap: var(--space-3);
   padding: var(--space-3);
diff --git a/docs/runtime-host-remote-access.md b/docs/runtime-host-remote-access.md
index e6a07fb16..b0baccc2e 100644
--- a/docs/runtime-host-remote-access.md
+++ b/docs/runtime-host-remote-access.md
@@ -104,9 +104,12 @@ ready; failure restores the previous service.
 
 ### Experimental direct peer
 
-The released CLI includes the native direct-peer transport for CLI and TUI use; the Host does not
-need Rust or a source checkout. Desktop support is not part of this milestone. After managed setup,
-enable it against the exact service target printed by setup:
+The released CLI and Desktop include the native direct-peer transport; the Host does not need Rust
+or a source checkout. For an SSH-managed Host, Desktop can enable it from that computer's management
+dialog and creates a separate experimental profile without deleting the SSH profile. Only one
+profile for the same State Root can be enabled at a time.
+
+The equivalent CLI flow uses the exact service target printed by setup:
 
 ```sh
 maka runtime-host service peer enable \
diff --git a/docs/runtime-host-remote-access.zh-CN.md b/docs/runtime-host-remote-access.zh-CN.md
index ee607cc00..a98625064 100644
--- a/docs/runtime-host-remote-access.zh-CN.md
+++ b/docs/runtime-host-remote-access.zh-CN.md
@@ -92,8 +92,11 @@ service;未指定 WebSocket port 时会保留现有端口。卸载 npm 包前
 
 ### 实验性 direct peer
 
-发布版 CLI 已包含供 CLI 和 TUI 使用的 direct peer native transport,Host 无需安装 Rust 或保留源码;
-Desktop 支持不在本里程碑范围内。完成 managed setup 后,使用 setup 输出的精确 service target 启用:
+发布版 CLI 与 Desktop 已包含 direct peer native transport,Host 无需安装 Rust 或保留源码。对于通过 SSH
+管理的 Host,可以在 Desktop 的电脑管理界面启用;Desktop 会创建独立的实验性 profile,不删除原 SSH
+profile。同一个 State Root 同时只能启用一个 profile。
+
+等价的 CLI 流程使用 setup 输出的精确 service target:
 
 ```sh
 maka runtime-host service peer enable \
diff --git a/packages/cli/src/__tests__/runtime-host-service-manager.test.ts b/packages/cli/src/__tests__/runtime-host-service-manager.test.ts
index b2f993667..992418df2 100644
--- a/packages/cli/src/__tests__/runtime-host-service-manager.test.ts
+++ b/packages/cli/src/__tests__/runtime-host-service-manager.test.ts
@@ -34,8 +34,10 @@ import { basename, dirname, join } from 'node:path';
 import { describe, it } from 'node:test';
 import {
   decodeRuntimeHostServiceManagementFrame,
+  encodeRuntimeHostServiceManagementFrame,
   RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY,
   RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV,
+  RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
   RUNTIME_HOST_OPERATOR_PROJECT_DIRECTORY_CONFIGURATION_REQUEST_ENV,
   RUNTIME_HOST_OPERATOR_PROCESS_LIFETIME_LOCK_CAPABILITY,
   RUNTIME_HOST_SERVICE_LOG_MAX_BYTES,
@@ -160,6 +162,7 @@ describe('managed Runtime Host service', () => {
         'service',
         'peer',
         'enable',
+        '--framed',
         '--listen',
         '/ip4/0.0.0.0/udp/44001/quic-v1',
         '--clear-coordination-relays',
@@ -174,6 +177,7 @@ describe('managed Runtime Host service', () => {
         kind: 'runtime-host-service-peer',
         action: 'enable',
         json: false,
+        framed: true,
         listenAddresses: ['/ip4/0.0.0.0/udp/44001/quic-v1'],
         coordinationRelays: [],
         expectedTarget: {
@@ -184,6 +188,23 @@ describe('managed Runtime Host service', () => {
       },
     );
     assert.equal(parseRuntimeHostCommand(['service', 'peer', 'disable']).kind, 'error');
+    for (const action of ['rotate', 'descriptor']) {
+      assert.equal(
+        parseRuntimeHostCommand([
+          'service',
+          'peer',
+          action,
+          '--framed',
+          '--expected-service-id',
+          'b'.repeat(64),
+          '--expected-root-path',
+          '/srv/maka',
+          '--expected-root-id',
+          'a'.repeat(64),
+        ]).kind,
+        'error',
+      );
+    }
     assert.equal(
       parseRuntimeHostCommand([
         'service',
@@ -1988,6 +2009,31 @@ describe('managed Runtime Host service', () => {
     assert.equal(frame.service.configurationFingerprint, undefined);
     assert.doesNotMatch(JSON.stringify(frame), /secret/u);
 
+    const futureFrame = decodeRuntimeHostServiceManagementFrame(
+      encodeRuntimeHostServiceManagementFrame({
+        ...frame,
+        operatorCapabilities: ['future-management-v2'],
+      }),
+    );
+    assert.deepEqual(
+      futureFrame?.kind === 'result' && futureFrame.action === 'status'
+        ? futureFrame.operatorCapabilities
+        : undefined,
+      ['future-management-v2'],
+    );
+
+    process.env[RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV] =
+      RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY;
+    const peerFrame = decodeRuntimeHostServiceManagementFrame(await run());
+    assert.deepEqual(
+      peerFrame?.kind === 'result' && peerFrame.action === 'status'
+        ? peerFrame.operatorCapabilities
+        : undefined,
+      [RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY],
+    );
+
+    process.env[RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV] =
+      RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY;
     process.env[RUNTIME_HOST_OPERATOR_PROJECT_DIRECTORY_CONFIGURATION_REQUEST_ENV] = '1';
     const configurationFrame = decodeRuntimeHostServiceManagementFrame(await run());
     if (configurationFrame?.kind !== 'result' || configurationFrame.action !== 'status') {
diff --git a/packages/cli/src/cli-core.ts b/packages/cli/src/cli-core.ts
index eb3fb53dc..15e5bcab3 100644
--- a/packages/cli/src/cli-core.ts
+++ b/packages/cli/src/cli-core.ts
@@ -352,6 +352,7 @@ export async function runMakaCli(
       return runRuntimeHostPeerManagementCli({
         action: command.action,
         json: command.json,
+        framed: command.framed ?? false,
         clientDataRoot: serviceDataRoots.clientDataRoot,
         defaultRootPath: serviceDataRoots.workspaceRoot,
         nodePath: process.execPath,
diff --git a/packages/cli/src/runtime-host-cli.ts b/packages/cli/src/runtime-host-cli.ts
index 489bbba63..61fc9d12c 100644
--- a/packages/cli/src/runtime-host-cli.ts
+++ b/packages/cli/src/runtime-host-cli.ts
@@ -100,6 +100,7 @@ export type RuntimeHostCliCommand =
       kind: 'runtime-host-service-peer';
       action: 'enable' | 'disable' | 'status' | 'rotate' | 'descriptor';
       json: boolean;
+      framed?: true;
       clientDataRoot?: string;
       listenAddresses: string[];
       coordinationRelays?: string[];
@@ -480,6 +481,7 @@ function parseServicePeerCommand(argv: string[]): RuntimeHostCliCommand {
   let clearCoordinationRelays = false;
   const options = parseManagedServiceOptions(argv.slice(1), {
     allowConfiguration: false,
+    allowFramed: true,
     flagOptions: {
       '--clear-coordination-relays': () => {
         if (clearCoordinationRelays) return error('Duplicate --clear-coordination-relays');
@@ -501,6 +503,9 @@ function parseServicePeerCommand(argv: string[]): RuntimeHostCliCommand {
     },
   });
   if ('kind' in options) return options;
+  if (options.framed && (action === 'rotate' || action === 'descriptor')) {
+    return error(`runtime-host service peer ${action} does not support --framed`);
+  }
   if (listenAddresses.some(hasEphemeralRuntimeHostPeerPort)) {
     return error('--listen requires a stable non-zero transport port');
   }
@@ -528,6 +533,7 @@ function parseServicePeerCommand(argv: string[]): RuntimeHostCliCommand {
     kind: 'runtime-host-service-peer',
     action,
     json: options.json,
+    ...(options.framed ? { framed: true as const } : {}),
     ...(clientDataRoot ? { clientDataRoot } : {}),
     listenAddresses,
     ...(clearCoordinationRelays
diff --git a/packages/cli/src/runtime-host-peer-management-command.ts b/packages/cli/src/runtime-host-peer-management-command.ts
index 70e3ff943..fb03b5c09 100644
--- a/packages/cli/src/runtime-host-peer-management-command.ts
+++ b/packages/cli/src/runtime-host-peer-management-command.ts
@@ -18,6 +18,11 @@
  */
 
 import { networkInterfaces } from 'node:os';
+import {
+  encodeRuntimeHostPeerManagementFrame,
+  type RuntimeHostPeerManagementFrame,
+  type RuntimeHostPeerStatus,
+} from '@maka/runtime-host/operator';
 import {
   configureRuntimeHostManagedPeer,
   manageRuntimeHostService,
@@ -35,6 +40,7 @@ import { createPlatformRuntimeHostServiceBackend } from './runtime-host-service-
 export interface RuntimeHostPeerManagementCliOptions {
   readonly action: 'enable' | 'disable' | 'status' | 'rotate' | 'descriptor';
   readonly json: boolean;
+  readonly framed?: boolean;
   readonly clientDataRoot: string;
   readonly defaultRootPath: string;
   readonly nodePath: string;
@@ -44,16 +50,6 @@ export interface RuntimeHostPeerManagementCliOptions {
   readonly expectedTarget?: RuntimeHostManagedServiceTarget;
 }
 
-interface RuntimeHostPeerStatus {
-  readonly schemaVersion: 1;
-  readonly state: 'not_configured' | 'disabled' | 'enabled';
-  readonly serviceState: string;
-  readonly peerId?: string;
-  readonly rootId?: string;
-  readonly routeHints: readonly string[];
-  readonly coordinationRelays: readonly string[];
-}
-
 interface RuntimeHostPeerManagementCliDeps {
   readonly createBackend: typeof createPlatformRuntimeHostServiceBackend;
   readonly managerOverrides: RuntimeHostServiceManagerOverrides;
@@ -165,10 +161,17 @@ async function runRuntimeHostPeerManagementLocked(
       'Direct peer is not enabled for the managed Runtime Host service',
     );
   }
-  if (options.json) {
-    deps.writeStdout(`${JSON.stringify({ ...status, ok: true, action: options.action })}\n`);
+  if (options.framed) {
+    if (options.action === 'descriptor') {
+      throw new TypeError('Direct-peer descriptor does not support framed output');
+    }
+    writePeerFrame({ kind: 'result', action: options.action, status }, deps);
+  } else if (options.json) {
+    deps.writeStdout(
+      `${JSON.stringify({ schemaVersion: 1, ...status, ok: true, action: options.action })}\n`,
+    );
   } else if (options.action === 'descriptor') {
-    deps.writeStdout(`${JSON.stringify(status)}\n`);
+    deps.writeStdout(`${JSON.stringify({ schemaVersion: 1, ...status })}\n`);
   } else {
     deps.writeStdout(formatPeerStatus(status));
   }
@@ -201,6 +204,13 @@ function writePeerFailure(
   message: string,
   deps: RuntimeHostPeerManagementCliDeps,
 ): void {
+  if (options.framed) {
+    if (options.action === 'rotate' || options.action === 'descriptor') {
+      throw new TypeError('Direct-peer action does not support framed output');
+    }
+    writePeerFrame({ kind: 'error', action: options.action, error: { code, message } }, deps);
+    return;
+  }
   if (options.json) {
     deps.writeStdout(
       `${JSON.stringify({
@@ -215,6 +225,13 @@ function writePeerFailure(
   deps.writeStderr(`${message}\n`);
 }
 
+function writePeerFrame(
+  frame: RuntimeHostPeerManagementFrame,
+  deps: Pick<RuntimeHostPeerManagementCliDeps, 'writeStdout'>,
+): void {
+  deps.writeStdout(encodeRuntimeHostPeerManagementFrame(frame));
+}
+
 async function readPeerStatus(
   options: RuntimeHostPeerManagementCliOptions,
   backend: ReturnType<typeof createPlatformRuntimeHostServiceBackend>,
@@ -236,7 +253,6 @@ async function readPeerStatus(
   const peer = result.service.config?.peer;
   if (!peer) {
     return {
-      schemaVersion: 1,
       state: 'not_configured',
       serviceState: result.service.state,
       routeHints: [],
@@ -244,13 +260,12 @@ async function readPeerStatus(
     };
   }
   return {
-    schemaVersion: 1,
     state: peer.enabled ? 'enabled' : 'disabled',
     serviceState: result.service.state,
     peerId: peer.peerId,
     ...(options.expectedTarget ? { rootId: options.expectedTarget.rootId } : {}),
     routeHints: expandWildcardListenAddresses(peer.listenAddresses),
-    coordinationRelays: peer.coordinationRelays,
+    coordinationRelays: [...peer.coordinationRelays],
   };
 }
 
diff --git a/packages/cli/src/runtime-host-service-management-command.ts b/packages/cli/src/runtime-host-service-management-command.ts
index dd6462689..613e38938 100644
--- a/packages/cli/src/runtime-host-service-management-command.ts
+++ b/packages/cli/src/runtime-host-service-management-command.ts
@@ -23,6 +23,7 @@ import {
   encodeRuntimeHostServiceManagementFrame,
   RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY,
   RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV,
+  RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
   RUNTIME_HOST_OPERATOR_PROJECT_DIRECTORY_CONFIGURATION_REQUEST_ENV,
   RUNTIME_HOST_OPERATOR_PROCESS_LIFETIME_LOCK_CAPABILITY,
   RUNTIME_HOST_SERVICE_ERROR_CODE_MAX_BYTES,
@@ -212,6 +213,7 @@ function requestedOperatorCapabilities(): {
   const requested = process.env[RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV];
   if (
     requested === RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY ||
+    requested === RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY ||
     requested === RUNTIME_HOST_OPERATOR_PROCESS_LIFETIME_LOCK_CAPABILITY
   ) {
     capabilities.push(requested);
diff --git a/packages/runtime-host/src/__tests__/peer-management-frame.test.ts b/packages/runtime-host/src/__tests__/peer-management-frame.test.ts
new file mode 100644
index 000000000..86377e5e8
--- /dev/null
+++ b/packages/runtime-host/src/__tests__/peer-management-frame.test.ts
@@ -0,0 +1,44 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import {
+  decodeRuntimeHostPeerManagementFrame,
+  encodeRuntimeHostPeerManagementFrame,
+} from '../operator/index.js';
+
+test('peer management frames preserve a bounded machine-readable descriptor', () => {
+  const frame = {
+    kind: 'result' as const,
+    action: 'enable' as const,
+    status: {
+      state: 'enabled' as const,
+      serviceState: 'running',
+      peerId: '12D3KooWpeer',
+      rootId: 'a'.repeat(64),
+      routeHints: ['/ip4/192.0.2.1/udp/41000/quic-v1'],
+      coordinationRelays: [],
+    },
+  };
+  assert.deepEqual(
+    decodeRuntimeHostPeerManagementFrame(encodeRuntimeHostPeerManagementFrame(frame)),
+    frame,
+  );
+});
diff --git a/packages/runtime-host/src/operator/index.ts b/packages/runtime-host/src/operator/index.ts
index bf53d7a58..00f414143 100644
--- a/packages/runtime-host/src/operator/index.ts
+++ b/packages/runtime-host/src/operator/index.ts
@@ -28,9 +28,18 @@ export {
   type RuntimeHostAccessManagementFrame,
 } from './access-management-frame.js';
 export { runtimeHostAccessCredentialFingerprint } from '../access-credential-identity.js';
+export {
+  RUNTIME_HOST_PEER_MANAGEMENT_FRAME_PREFIX,
+  decodeRuntimeHostPeerManagementFrame,
+  encodeRuntimeHostPeerManagementFrame,
+  type RuntimeHostPeerManagementAction,
+  type RuntimeHostPeerManagementFrame,
+  type RuntimeHostPeerStatus,
+} from './peer-management-frame.js';
 export {
   RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY,
   RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV,
+  RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
   RUNTIME_HOST_OPERATOR_PROJECT_DIRECTORY_CONFIGURATION_REQUEST_ENV,
   RUNTIME_HOST_OPERATOR_PROCESS_LIFETIME_LOCK_CAPABILITY,
   RUNTIME_HOST_OPERATOR_UPDATE_SCHEDULER_CAPABILITY,
diff --git a/packages/runtime-host/src/operator/peer-management-frame.ts b/packages/runtime-host/src/operator/peer-management-frame.ts
new file mode 100644
index 000000000..d00e7756c
--- /dev/null
+++ b/packages/runtime-host/src/operator/peer-management-frame.ts
@@ -0,0 +1,97 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { z } from 'zod';
+
+export const RUNTIME_HOST_PEER_MANAGEMENT_FRAME_PREFIX = 'MAKA_RUNTIME_HOST_PEER_MANAGEMENT_V1 ';
+const FRAME_MAX_BYTES = 128 * 1024;
+
+const ACTION_SCHEMA = z.enum(['enable', 'disable', 'status']);
+const boundedString = (maxBytes: number) =>
+  z.string().refine((value) => Buffer.byteLength(value, 'utf8') <= maxBytes);
+const ADDRESS_SCHEMA = boundedString(2 * 1024);
+const STATUS_SCHEMA = z
+  .object({
+    state: z.enum(['not_configured', 'disabled', 'enabled']),
+    serviceState: boundedString(128),
+    peerId: boundedString(160).optional(),
+    rootId: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/u)
+      .optional(),
+    routeHints: z.array(ADDRESS_SCHEMA).max(16),
+    coordinationRelays: z.array(ADDRESS_SCHEMA).max(16),
+  })
+  .strict();
+
+const FRAME_SCHEMA = z.discriminatedUnion('kind', [
+  z
+    .object({
+      kind: z.literal('result'),
+      action: ACTION_SCHEMA,
+      status: STATUS_SCHEMA,
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal('error'),
+      action: ACTION_SCHEMA,
+      error: z
+        .object({
+          code: boundedString(128),
+          message: boundedString(2 * 1024),
+        })
+        .strict(),
+    })
+    .strict(),
+]);
+
+export type RuntimeHostPeerManagementAction = z.infer<typeof ACTION_SCHEMA>;
+export type RuntimeHostPeerStatus = z.infer<typeof STATUS_SCHEMA>;
+export type RuntimeHostPeerManagementFrame = z.infer<typeof FRAME_SCHEMA>;
+
+export function encodeRuntimeHostPeerManagementFrame(
+  frame: RuntimeHostPeerManagementFrame,
+): string {
+  const encoded = Buffer.from(JSON.stringify(FRAME_SCHEMA.parse(frame)), 'utf8').toString(
+    'base64url',
+  );
+  if (Buffer.byteLength(encoded, 'utf8') > FRAME_MAX_BYTES) {
+    throw new RangeError('Runtime Host peer management frame exceeds the encoded size limit');
+  }
+  return `${RUNTIME_HOST_PEER_MANAGEMENT_FRAME_PREFIX}${encoded}\n`;
+}
+
+export function decodeRuntimeHostPeerManagementFrame(
+  line: string,
+): RuntimeHostPeerManagementFrame | undefined {
+  const marker = line.indexOf(RUNTIME_HOST_PEER_MANAGEMENT_FRAME_PREFIX);
+  if (marker < 0) return undefined;
+  try {
+    const encoded = line.slice(marker + RUNTIME_HOST_PEER_MANAGEMENT_FRAME_PREFIX.length).trim();
+    if (encoded.length === 0 || Buffer.byteLength(encoded, 'utf8') > FRAME_MAX_BYTES) {
+      return undefined;
+    }
+    const value: unknown = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
+    const decoded = FRAME_SCHEMA.safeParse(value);
+    return decoded.success ? decoded.data : undefined;
+  } catch {
+    return undefined;
+  }
+}
diff --git a/packages/runtime-host/src/operator/service-management-frame.ts b/packages/runtime-host/src/operator/service-management-frame.ts
index b58e53e2a..2649d6d35 100644
--- a/packages/runtime-host/src/operator/service-management-frame.ts
+++ b/packages/runtime-host/src/operator/service-management-frame.ts
@@ -34,6 +34,7 @@ export const RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY = 'access-manage
 export const RUNTIME_HOST_OPERATOR_PROJECT_DIRECTORY_CONFIGURATION_REQUEST_ENV =
   'MAKA_RUNTIME_HOST_OPERATOR_PROJECT_DIRECTORY_CONFIGURATION_REQUEST';
 export const RUNTIME_HOST_OPERATOR_PROCESS_LIFETIME_LOCK_CAPABILITY = 'process-lifetime-lock-v1';
+export const RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY = 'peer-management-v1';
 export const RUNTIME_HOST_OPERATOR_UPDATE_SCHEDULER_CAPABILITY = 'update-scheduler-v1';
 export const RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST_ENV =
   'MAKA_RUNTIME_HOST_OPERATOR_CAPABILITY_REQUEST';
@@ -90,6 +91,7 @@ const INSTALLED_SERVICE_STATES = ['stopped', 'starting', 'running', 'failed'] as
 const SERVICE_STATES = ['not_installed', ...INSTALLED_SERVICE_STATES] as const;
 const OPERATOR_CAPABILITIES = [
   RUNTIME_HOST_OPERATOR_ACCESS_MANAGEMENT_CAPABILITY,
+  RUNTIME_HOST_OPERATOR_PEER_MANAGEMENT_CAPABILITY,
   RUNTIME_HOST_OPERATOR_PROCESS_LIFETIME_LOCK_CAPABILITY,
   RUNTIME_HOST_OPERATOR_UPDATE_SCHEDULER_CAPABILITY,
 ] as const;
@@ -257,7 +259,9 @@ const SERVICE_RESULT_COMMON = {
   schemaVersion: z.literal(1),
   kind: z.literal('result'),
   service: SERVICE_SUMMARY_SCHEMA,
-  operatorCapabilities: z.array(z.enum(OPERATOR_CAPABILITIES)).max(16).optional(),
+  // Unknown tokens are ignored by callers. Keeping the wire field open lets
+  // older Clients decode status from a newer operator.
+  operatorCapabilities: z.array(boundedNonEmptyString(FIELD_MAX_BYTES)).max(16).optional(),
   retainedStateRoot: boundedString(PATH_MAX_BYTES).optional(),
   logs: boundedString(RUNTIME_HOST_SERVICE_LOG_MAX_BYTES).optional(),
 } as const;
diff --git a/scripts/package-macos-arm64.mjs b/scripts/package-macos-arm64.mjs
index 34779367b..078ba0c0b 100644
--- a/scripts/package-macos-arm64.mjs
+++ b/scripts/package-macos-arm64.mjs
@@ -91,6 +91,8 @@ export async function packageMacosArm64({
 
   await run('npm', ['run', 'clean']);
   await run('npm', ['run', 'build']);
+  await run('npm', ['run', 'build:runtime-host-peer']);
+  await run('npm', ['run', 'check:runtime-host-peer-notices']);
   await run('npm', ['run', 'check:release']);
   await remove(releaseDirectory, { recursive: true, force: true });
   await run('npm', ['--workspace', '@maka/desktop', 'run', 'package:macos-arm64']);
diff --git a/scripts/package-windows-x64.mjs b/scripts/package-windows-x64.mjs
index 46cb20441..515d95b87 100644
--- a/scripts/package-windows-x64.mjs
+++ b/scripts/package-windows-x64.mjs
@@ -103,6 +103,8 @@ export async function packageWindowsX64({
 
   await run('npm', ['run', 'clean']);
   await run('npm', ['run', 'build']);
+  await run('npm', ['run', 'build:runtime-host-peer']);
+  await run('npm', ['run', 'check:runtime-host-peer-notices']);
   await run('cargo', ['build', '--manifest-path', sandboxManifestPath, '--release', '--locked']);
   await run('npm', ['run', 'check:windows-cargo-notices']);
   await mkdir(sandboxResourceDirectory, { recursive: true });
diff --git a/scripts/verify-packaged-app.mjs b/scripts/verify-packaged-app.mjs
index 43c51b85c..bdb84e538 100644
--- a/scripts/verify-packaged-app.mjs
+++ b/scripts/verify-packaged-app.mjs
@@ -1022,6 +1022,9 @@ export async function assertPackagedResources(
     // artifacts that were correct when they shipped. The canonical icon itself
     // is `requireCanonicalIcon` above, not this.
     requireAppIconCatalog = true,
+    // Current Desktop builds ship the direct-peer Client addon beside its Rust
+    // notices. Upgrade baselines may predate both resources.
+    requireDirectPeerArtifact = true,
   } = {},
 ) {
   if (bundledGitContract !== 'forbidden' && bundledGitContract !== 'legacy-required') {
@@ -1042,6 +1045,12 @@ export async function assertPackagedResources(
       : []),
     ...(requireCanonicalIcon ? [join('assets', 'icon.png')] : []),
     join('workers', 'filesystem-worker.js'),
+    ...(requireDirectPeerArtifact
+      ? [
+          join('runtime-host-peer', 'maka_runtime_host_peer.node'),
+          join('licenses', 'runtime-host-peer', 'THIRD_PARTY_NOTICES.txt'),
+        ]
+      : []),
     // The picker's catalog is read at runtime, and Electron reports a missing
     // file as an empty image rather than an error — a packaging change that
     // dropped one would ship a blank tile silently.
diff --git a/scripts/verify-packaged-app.test.mjs b/scripts/verify-packaged-app.test.mjs
index 1f7596d19..6db7792b7 100644
--- a/scripts/verify-packaged-app.test.mjs
+++ b/scripts/verify-packaged-app.test.mjs
@@ -58,6 +58,7 @@ test('legacy packaged resources require the historical bundled Git contract', as
     requireWindowsSandbox: false,
     bundledGitContract: 'legacy-required',
     requireCanonicalIcon: false,
+    requireDirectPeerArtifact: false,
   });
 
   for (const path of [
diff --git a/scripts/verify-windows-x64.mjs b/scripts/verify-windows-x64.mjs
index 2aea9189b..219a7c707 100644
--- a/scripts/verify-windows-x64.mjs
+++ b/scripts/verify-windows-x64.mjs
@@ -146,6 +146,7 @@ export async function verifyPackagedWindowsApp(
     bundledGitContract: requiresCurrentContract ? 'forbidden' : 'legacy-required',
     requireCanonicalIcon: requiresCurrentContract,
     requireAppIconCatalog: requiresCurrentContract,
+    requireDirectPeerArtifact: requiresCurrentContract,
   });
   if (requiresCurrentContract) await assertPackagedDependencyClosure(resources);
   else await requirePath(join(resources, 'git', 'cmd', 'git.exe'));


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org