Eve library

Local Cloud-Agent Simulation

Guide

Revision 1

On this page

Status: Phase 180.C.14.06 reference procedure.

This document defines the local simulation used before Hetzner or AWS deployment exists. It models a cloud agent as a separate local process that talks only to the Bellona MCP gateway surface. The simulated agent must not connect to the remote host, Blender, Chrome/CDP, desktop fallback helpers, or same-LAN host ports directly.

Topology#

Role Local Simulation Process Authority Boundary
Cloud agent Any MCP-capable client process or test harness Calls MCP tools/resources only
MCP gateway process pnpm nx stdio @bellona/mcp-gateway Auth/session binding plus MCP translation
Remote Gateway state In-process structural gateway wiring for now Device/session/command/audit authority
Remote Host Existing fake/fixture host state for this stage No direct connection from simulated agent
Adapters Gateway-dispatched command targets only No direct LAN, CDP, Blender, or desktop IO

The local simulation intentionally treats the MCP process as if it were a cloud edge client. The only allowed command path is:

  1. Cloud-agent MCP client.
  2. Bellona MCP gateway tool/resource.
  3. Bellona Remote Gateway structural boundary.
  4. Gateway policy, approval, revocation, schema, session, command, and audit controls.
  5. Host/adapters after gateway dispatch.

Prerequisites#

  • pnpm install has already completed for the workspace.
  • pnpm nx test @bellona/mcp-gateway --skip-nx-cache --verbose passes.
  • The MCP gateway is configured with remoteControlAuthSession.mode: "required" for any remote/cloud transport.
  • The simulated client receives an MCP authInfo payload with:
    • resource set to the MCP gateway resource identifier.
    • clientId for the cloud agent.
    • Required scopes for the action being tested.
    • Gateway-bound participantId, sessionId, and allowedSessionIds.

Local Stdio Harness#

The first-stage local harness is stdio because 180.C.14 has not yet added a Streamable HTTP transport target. Use it to prove agent routing, tool/resource shape, auth/session binding, and gateway failure behavior before cloud deployment.

sh
pnpm nx stdio @bellona/mcp-gateway

A separate MCP client process should connect to that stdio process and run this minimal sequence:

text
resources/list
resources/read bellona://remote-control/devices/active/capabilities
tools/call device.list
tools/call session.start
tools/call blender.scene.info
tools/call browser.navigate
tools/call desktop.screenshot
resources/read bellona://remote-control/commands/last-result
tools/call session.stop

For local automated proof, libs/bellona/mcp-gateway unit tests already exercise this path over MCP SDK in-memory transports:

  • remote-control-tools.test.ts proves tool registration, gateway dispatch, and auth-bound client/session propagation.
  • remote-control-resources.test.ts proves resource listing and reads through gateway state methods.
  • remote-control-bypass.test.ts proves schema failures and gateway policy/approval/revocation errors remain MCP tool errors.

No Direct LAN Rule#

During this simulation, the cloud-agent process must not:

  • Open Blender localhost ports, Chrome/CDP ports, desktop fallback helpers, or host WebSocket connections directly.
  • Use same-LAN host addresses or mDNS names.
  • Read or write Remote Gateway persistent store files directly.
  • Reuse host pairing or host-token credentials.
  • Set clientId tool arguments to impersonate another MCP client.

The MCP gateway auth binding overrides tool-supplied clientId values when a remote/cloud client is authenticated. A simulation that succeeds only by direct LAN access is invalid for Phase 180.

Expected Evidence#

Record the following for a local cloud-agent simulation run:

  • MCP server command line and commit SHA.
  • Auth mode, resource audience, client id, participant id, and bound session id.
  • resources/list output showing all four Phase 180 MCP resources.
  • tools/list output showing all eight Phase 180 MCP tools.
  • The session id returned by session.start.
  • The command ids and idempotency keys returned by command dispatches.
  • The last-result resource after at least one command result.
  • The session.stop result.
  • Confirmation that no direct LAN adapter endpoint was opened by the agent.

Promotion Path#

This local simulation is intentionally not the final cloud deployment. The next items promote the same flow:

  • 180.C.14.07: Hetzner reference deployment notes.
  • 180.C.14.08: AWS reference deployment notes.
  • 180.C.14.09: Cloud-agent MVP smoke flow using the deployed gateway path.

The same no-direct-LAN rule remains in force for those stages.