Skip to content

Research: physical host registry + isolated artifact-worker donor analysis from local-workspace-mcp #123

Open
Open
Research: physical host registry + isolated artifact-worker donor analysis from local-workspace-mcp#123

Description

@James3014
James3014
opened on Sep 13, 2026

Status / intent

RESEARCH COMPLETE — DESIGN CANDIDATE FOR FUTURE IMPLEMENTATION. AUTO_CHAIN=false.

This Issue records a bounded source-level adoption study of:

  • donor: arumwu/local-workspace-mcp
  • donor revision: 5f05e5bb0b83c0e0aaa8a56a3d0270bd1fc951fb (2026-09-12)
  • target: James3014/devspace
  • target revision inspected: ab22dc9d0360bd02d00892734a5c51cdd0873f39 (2026-09-12)

Purpose: preserve the useful mechanisms and the rejection rationale so future implementation does not repeat the same research or accidentally introduce a second local execution authority.

This Issue is not implementation authorization, install authority, merge authority, Nexus authority, or production-readiness evidence.

Executive conclusion

Do not integrate local-workspace-mcp as a second DevSpace coding/runtime control plane.

The project overlaps heavily with current DevSpace in:

  • file read/write/edit/search;
  • shell/process execution;
  • local project access;
  • MCP exposure;
  • local development workflows.

Current DevSpace already has materially stronger lifecycle/identity controls for engineering execution, including durable host-operation attemptKey semantics, exact process ownership, status/reconcile/cancel, logical local-agent identity, daemon durability, typed failures, workspace fencing, and no-blind-replay behavior.

The donor has two useful patterns:

  1. Named physical-device registry / MCP-over-stdio-or-SSH abstraction — real candidate for DevSpace design work.
  2. Read-only-input / bounded-output isolated document/artifact worker — reference-only candidate for a later artifact-processing lane.

The donor's generic process/session tools and full-OS MCP mode should not be adopted.

1. Donor evidence — named devices

Primary source:

src/local_workspace_mcp/devices.py

Observed mechanism at donor revision:

private owner devices.json
        |
        v
named device
  command + argv
        |
        v
stdio MCP session
  (SSH may be the configured command)
        |
        v
remote MCP server
        |
        +--> list_device_tools(device)
        +--> call_device_tool(device, tool, arguments)

Useful properties:

  • device configuration is owner-supplied, not discovery-based;
  • configuration must be outside the shared workspace;
  • configuration file must have mode 0600;
  • bounded number of named devices (max 16 in donor source);
  • remote sessions are cached/reused;
  • credentials are not returned through the MCP tool surface;
  • recursive device routing is explicitly rejected;
  • remote tool schemas can be inspected before invocation;
  • no hosted device account/discovery service is introduced.

What this proves

It proves a small, understandable host registry + transport binding pattern can sit above MCP connections.

What it does NOT prove

The donor's own feature documentation states:

  • two independent stdio agents were exercised;
  • physical SSH multi-machine checks remain incomplete/outstanding;
  • real ChatGPT client acceptance remains incomplete;
  • the project is alpha.

Therefore donor evidence supports architecture/reference value, not distributed-runtime reliability.

2. Real DevSpace gap identified

Current DevSpace workspace authority is effectively local-machine scoped:

DEVSPACE_ALLOWED_ROOTS
       -> open_workspace
       -> workspaceId
       -> file/shell/worker tools

This is correct for one host, but the workspace identity does not currently model an explicit physical-machine dimension.

A future multi-machine DevSpace needs to distinguish at least:

host_id
!= workspace_id
!= worker_id
!= carrier/conversation_id
!= operation_id / attemptKey

The physical location of execution must not become task authority.

Proposed narrow architecture direction

ChatGPT / coordinator
        |
        v
DevSpace Controller
        |
        v
Known Host Registry
  - host_id
  - exact DevSpace/runtime identity
  - admitted transport
  - capabilities
  - health/readback
  - policy
        |
        v
Remote DevSpace endpoint
        |
        v
open_workspace on that host
        |
        v
workspace_id
        |
        v
existing bounded DevSpace tools / workers

Key invariant:

host location != execution authority

A host change, disconnect, reconnect, or replacement must not mint a new worker/task/operation authority or silently make retry safe.

3. Mechanisms worth adopting

A. Explicit named hosts

Adopt the concept of an owner-defined host registry rather than broad network discovery.

Candidate properties:

  • stable opaque hostId / host name;
  • explicit transport configuration;
  • exact expected remote DevSpace/build identity;
  • allowed capabilities or role ceiling;
  • health state separated from task state;
  • private owner configuration outside workspaces;
  • secret material never returned to workers/models.

B. Private bounded configuration

Donor's 0600 owner config is a good pattern.

DevSpace should preserve its own config/state conventions and not copy donor file layout mechanically.

C. Session reuse as transport optimization

Persistent/cached remote connections may reduce SSH/stdin startup cost.

However cached connectivity must remain transport state only. A cached session must not become:

  • task authority;
  • workspace authority;
  • worker identity;
  • operation completion proof.

D. Explicit remote capability readback

A future host registry may expose bounded read-only equivalents of:

host_registry_list
host_registry_status
host_capabilities

But the controller should prefer a known DevSpace contract/version over arbitrary dynamic remote MCP schemas.

4. Mechanisms explicitly NOT to adopt

A. Generic call_device_tool

Do not expose a general-purpose controller equivalent of:

call_device_tool(host, arbitraryToolName, arbitraryArguments)

Reason: it allows the remote MCP server's dynamic tool surface to become an implicit execution-authority expansion point.

DevSpace should route only to a bounded, versioned remote DevSpace contract or explicitly admitted adapter surface.

B. Arbitrary remote MCP server as authority

Do not let any paired MCP server dynamically define filesystem/shell/process authority.

Remote schema availability is not admission.

C. Donor Full Mode / full OS user execution

The donor security model explicitly states its Full Mode intentionally allows arbitrary OS-user execution, network access, and destructive operations; allowedDirectories, command blocklists, and tool annotations are not a sandbox/authorization boundary.

That model conflicts with DevSpace's current direction toward bounded workspace, executable, path, process, operation, and reconciliation identity.

D. Second route/controller/verifier

Do not introduce:

  • a second DevSpace route authority;
  • a second Nexus route authority;
  • a parallel verifier/receipt system;
  • a second task/worker identity registry;
  • a generic MCP federation layer that bypasses existing DevSpace authority contracts.

5. Process/session lifecycle comparison — no adoption needed

The donor exposes useful generic process tools such as:

host_start_process
host_interact_with_process
host_read_process_output
host_list_sessions
host_force_terminate
host_kill_process

This is an improvement over one-shot shell for a basic MCP, but current DevSpace is already beyond this level.

Current DevSpace host operation model

Current docs/host-operations.md defines:

host_operation_preflight
host_operation_start
host_operation_status
host_operation_reconcile
host_operation_cancel

with startup-bound:

  • OAuth client identity;
  • exact executable path + SHA-256;
  • exact argv;
  • canonical cwd;
  • allowed read/write paths;
  • durable attemptKey;
  • wall/idle bounds;
  • exact process ownership;
  • replay/reconcile behavior;
  • no raw-PID cancellation authority;
  • unknown outcome preserved after restart when physical completion cannot be proven.

Current DevSpace local-agent model

Current docs/local-agent-daemon.md already separates:

logical agent identity
!= provider session identity
!= disposable live runtime

and provides:

  • durable SQLite state;
  • daemon-owned provider runtimes;
  • restart recovery;
  • typed error codes;
  • structured retryability;
  • bounded graceful shutdown;
  • stale starting/running reconciliation.

Decision: donor process/session management is not a DevSpace adoption target.

6. Isolated artifact/document worker — reference-only donor pattern

Primary donor source:

src/local_workspace_mcp/runner.py

Observed sandbox shape:

input workspace
   -> read-only bind mount
Docker worker
   - --network=none
   - --read-only
   - --cap-drop=ALL
   - no-new-privileges
   - pids limit
   - memory limit
   - CPU limit
   - non-root user
   - bounded tmpfs
   - wall timeout
   - stdout/stderr output limit
   -> /output writable only

The donor has an opt-in real Docker test that creates/reopens:

  • DOCX;
  • XLSX;
  • PPTX;
  • PDF;
  • PNG;
  • Chinese DOCX rendering;
  • LibreOffice spreadsheet recalculation.

It also force-cleans the named Docker container after timeout because local CLI timeout is not proof that the container stopped.

Design value

This is a good donor pattern for a future DevSpace artifact worker:

bounded source evidence (read-only)
        -> isolated renderer/transform worker
        -> bounded outputs
        -> independent artifact verification

Current disposition

REFERENCE_ONLY — do not modify DevSpace for this now unless a concrete product requirement appears for Word/Excel/PPT/PDF artifact generation or engineering-report production.

If activated later, create a separate implementation Issue rather than mixing document transformation into the physical-host registry.

7. Relationship to existing DevSpace Issues

#15 — Dev MCP reliability

Owns single-control-plane reliability: host binding, worker startup, timeout/reconciliation, provider readiness, error taxonomy.

This research does not replace #15.

#98 — OWNER_DIRECT host-operation contract

Owns bounded host effects on a local macOS host, with executable/path/process/reconciliation authority.

A future physical-host layer should reuse #98-style effect semantics per host, not create a new generic remote-shell model.

#105 — macOS elastic ChatGPT worker runtime lifecycle

Owns worker-carrier lifecycle (ensure, wake, park, recover, scale). It already requires:

workerId != carrier/conversation ID

A future host layer should extend the same separation:

workerId != carrierId != hostId != workspaceId != operationId

Host lifecycle must never become Swarm/task authority.

#117 — macOS zero-touch ChatGPT Web worker runtime pool

Owns the first real ChatGPT Web carrier pool implementation.

This research is orthogonal:

Do not make #117 depend on a multi-host implementation unless a proven product need appears.

8. Candidate design constraints for future implementation

If/when implementation is authorized, first freeze these invariants.

Identity

host_id
workspace_id
worker_id
carrier_id
operation_id / attemptKey

must remain independently typed and attributable.

Remote host admission

A remote host should not be considered executable merely because SSH connects.

Require fresh readback of at least:

  • expected host identity;
  • expected DevSpace runtime/build identity;
  • admitted protocol/capability version;
  • target workspace root availability;
  • required capability set;
  • host health.

Workspace authority remains explicit

Remote execution should still require:

host_id
-> remote DevSpace identity
-> open_workspace(target)
-> workspace_id
-> bounded operation

No path-string fallback.

No blind cross-host failover

If execution outcome on host A is unknown:

host A unreachable
!= no effect occurred
!= safe to send same effect to host B

Same-operation reconciliation/fencing remains mandatory.

Capability is not task authority

A host may advertise:

  • CPU/GPU;
  • filesystem roots;
  • local models;
  • provider runtimes;
  • artifact capability;
  • OS/platform.

These are scheduling inputs only. They do not grant worker/task/mutation/acceptance authority.

Security

Do not persist or surface raw:

  • SSH private keys;
  • bearer tokens;
  • cookies;
  • provider secrets;
  • remote auth stores.

Prefer existing OS SSH/auth infrastructure and exact host-key verification where SSH is used.

9. Minimum future gate sequence

G0 — design / overlap audit

Before implementation, rebind current DevSpace source and confirm no overlapping authority with:

Deliver one SSOT ownership map.

G1 — read-only Host Registry

Implement only:

host_registry_list
host_registry_status
host_capabilities

with private explicit configuration and exact remote DevSpace identity readback.

No remote mutation.

G2 — remote workspace open/read canary

On two owner-controlled Macs, prove:

host A controller
-> exact host B
-> exact remote DevSpace
-> open_workspace
-> read-only file/read/status

with no arbitrary dynamic MCP tool routing.

G3 — one bounded remote operation

Reuse existing DevSpace operation/workspace authority to perform one harmless exact operation on host B.

Prove:

  • exact host/workspace/operation attribution;
  • same-attempt replay is idempotent;
  • disconnect produces reconciliation, not blind repeat;
  • wrong host/workspace/operation identity fails closed.

G4 — hostile/recovery controls

Test at minimum:

  • unknown host;
  • host-key / identity mismatch;
  • wrong DevSpace build/protocol;
  • remote workspace outside admitted roots;
  • dropped transport after possible effect;
  • controller restart;
  • remote DevSpace restart;
  • host offline before effect;
  • host offline after possible effect;
  • attempt replay on same host;
  • attempted cross-host replay while old effect remains unknown.

G5 — optional scheduling integration

Only after G1-G4, consider exposing host capabilities to higher-level worker placement.

Scheduling must remain advisory/selection input, not execution authority.

10. Success criteria for a future Physical Host Registry implementation

A future implementation is successful only if DevSpace can support:

known host
-> verified DevSpace identity
-> explicit workspace
-> bounded operation
-> exact receipt/reconciliation

without introducing:

  • arbitrary remote MCP execution;
  • duplicated task/worker authority;
  • path-based implicit grants;
  • blind cross-host retry;
  • host health as completion proof;
  • a second router/verifier/receipt authority.

Suggested post-G4 claim ceiling:

DEVSPACE_MULTI_HOST_BOUNDED_EXECUTION_CANARY_PASS

This would prove only the bounded host/workspace transport layer. It would not prove autonomous placement, production distributed execution, Nexus Workforce admission, acceptance, merge, or deployment.

11. Current adoption disposition

Donor mechanism Decision Reason
Named host/device registry DESIGN_CANDIDATE real DevSpace capability gap
Private 0600 owner host config ADOPT_PATTERN clear authority boundary
Explicit names / no discovery ADOPT_PATTERN minimizes accidental authority expansion
Cached SSH/stdio MCP session REFERENCE transport optimization only
Generic call_device_tool REJECT arbitrary remote tool authority
Arbitrary paired MCP server REJECT schema/authority drift
Full OS-user MCP mode REJECT conflicts with bounded DevSpace authority model
Generic process/session tools NO_NEED DevSpace lifecycle is already stronger
Document Docker worker REFERENCE_ONLY useful later, no current product gap
Whole-project dependency/install REJECT high overlap + second execution surface

Exact next gate

DEVSPACE_PHYSICAL_HOST_REGISTRY_G0_AUTHORITY_AND_IDENTITY_DESIGN_FREEZE

Rebind current source and produce one bounded design proving where host_id lives, how it composes with workspace_id, worker_id, carrier identity, Host Operations and operation reconciliation, and which existing component remains SSOT for each authority.

Only after that gate should an implementation Task/PR be authorized.

Maximum supportable claim now

local-workspace-mcp provides a useful donor pattern for explicit named physical hosts and an isolated document worker, but does not justify introducing a second DevSpace execution authority. DevSpace currently lacks an explicit physical-host identity layer; future implementation should add host_id -> verified remote DevSpace -> workspace_id while preserving existing worker/task/operation authority and no-blind-retry semantics.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions