CodeMantle: Distributed OpenCode Control Plane

CodeMantle started from one painful reality: my strongest machine was at home, but my day moved across devices and locations.

I wanted to open a project folder on that home machine, start an OpenCode session there, and continue coding remotely — without giving broad shell access to the whole computer.

So I built CodeMantle as a split-plane architecture:

• Control plane for auth, policy, API/UI, and orchestration dispatch.
• Agent daemon for host-local execution boundaries, path safety, and OpenCode lifecycle control.
• Desktop operator app for setup UX, sidecar lifecycle, and tray controls.
• Unified CLI ('codemantle') for panel/agent bootstrap flows.

Repository: https://github.com/XQuestCode/CodeMantle

Core technical objective

Enable secure remote coding against a specific folder on a PC by:

1. Exposing no inbound host ports on managed devices.
2. Routing all orchestration through an authenticated outbound tunnel.
3. Enforcing root/path/symlink boundaries at daemon runtime.
4. Starting OpenCode only for validated workspace paths.
5. Keeping operator actions role-gated and ownership-scoped.

Practical workflow

1. Register a device and choose a workspace root.
2. From another location/device, select a folder inside that allowed root.
3. Start an OpenCode session remotely.
4. Stream prompts, responses, and status through the control plane.
5. Keep access constrained to policy + ownership boundaries.

This makes OpenCode feel location-independent while still respecting local host boundaries.

Architecture and infrastructure model

Split planes

• Control plane ('@codemantle/panel'): identity, RBAC, route authorization, orchestration HTTP API, UI, and config governance.
• Agent daemon ('@codemantle/agent-daemon'): local policy boundary for filesystem/process/JIT controls and OpenCode lifecycle handling.
• Desktop operator app (Tauri): sidecar setup, health checks, autostart/tray controls, and endpoint configuration.
• Unified CLI ('codemantle'): operator routing for panel/agent launch flows.

Transport and protocol

• Reverse WebSocket connection from daemon to control plane.
• Compact additive envelope: '{ v: 1, t: "message_type", i: requestId }'.
• Handshake uses nonce + timestamp + HMAC ('h1'/'h2').
• Protocol floor checks allow 'UPDATE_REQUIRED' rejection for outdated agents.

Deployment baseline

• Public TLS edge (Nginx/Caddy/Traefik) on 443.
• Internal control-plane listeners (WS/API split) behind reverse proxy.
• PM2/systemd process supervision.
• Outbound daemon connectivity from managed hosts.

Runtime mechanics

1) Reverse-tunnel control model

• Agent daemon initiates outbound WebSocket connections to the control plane.
• Handshake uses nonce + timestamp + HMAC ('h1'/'h2').
• Protocol version floor can reject outdated agents safely.

2) Local orchestration boundary

• Daemon manages OpenCode process lifecycle per validated workspace path.
• Enforces root/path/symlink containment before filesystem operations.
• Persists continuity artifacts for restart recovery (registry + logs + snapshots).

This is the key security idea: remote operation is allowed, but only inside explicitly permitted folder boundaries.

3) Operator API surface

• Device inventory and liveness.
• Session lifecycle (start, status, terminate, snapshot).
• Filesystem and Git operation dispatch.
• Prompt routing and guarded port proxy workflows.

4) Security and policy controls

• Role-gated API access ('viewer', 'operator', 'admin', 'owner').
• CSRF checks on mutating control-plane routes.
• JIT credential binding with TTL and kill-switch support.

In short: remote coding convenience with guardrails, not unrestricted remote control.

Protocol and API depth

Protocol operation families

• Handshake/liveness: 'h1', 'h2', 'p', 'pl'
• Session control: 'si', 'st', 'sq', 'sv', 'sl', 'sp'
• Proxy stream: 'pr', 'pv', 'ps', 'pe'
• Setup/config/JIT: 'cf', 'cg', 'cu', 'cv', 'cc', 'jk', 'jv'
• Filesystem/Git command plane: 'md..rp', 'gi..gv'

HTTP endpoint classes

• Auth/session, devices, setup, session lifecycle, config schema/compile/push/status
• Filesystem operations (dir/mkdir/rmdir/rename)
• Git operations (status/init/clone/add/commit/push/pull/branch/checkout/config)
• Prompt dispatch and guarded port proxy routes

Reliability and failure posture

• Reconnect and heartbeat logic for tunnel liveness.
• Health-gated OpenCode startup with bounded retries/backoff.
• Session continuity artifacts for restart reconstruction.
• Bounded payload handling for protocol paths.

Known scaling caveat

Current live routing/session ownership/pending request state is primarily in-memory on the control plane, so horizontal scale requires explicit shared-state coordination.

Deployment posture

Current production baseline:

• Control plane behind TLS reverse proxy.
• Agent daemons connect outbound over 'wss'.
• PM2/systemd for service supervision.

Current caveat: live control-plane routing/state is in-memory, so horizontal scale requires explicit shared-state coordination.

Package surfaces

• Unified CLI: https://www.npmjs.com/package/codemantle
• Panel package: https://www.npmjs.com/package/@codemantle/panel
• Agent package: https://www.npmjs.com/package/@codemantle/agent-daemon

References

• Control plane runtime: https://github.com/XQuestCode/CodeMantle/tree/main/apps/control-plane
• Agent daemon runtime: https://github.com/XQuestCode/CodeMantle/tree/main/packages/agent-daemon
• Desktop app: https://github.com/XQuestCode/CodeMantle/tree/main/apps/desktop-app
• Unified CLI: https://github.com/XQuestCode/CodeMantle/tree/main/packages/codemantle
• Architecture: https://github.com/XQuestCode/CodeMantle/blob/main/docs/architecture.md
• Security model: https://github.com/XQuestCode/CodeMantle/blob/main/docs/security-model.md
• Deployment guide: https://github.com/XQuestCode/CodeMantle/blob/main/docs/deployment.md