ship’s manual · guide

Architecture

1Helm is a compact local control plane around many persistent employee worlds.

Captain
  └─ #main / Skipper ── host · credentials · fleet · cross-channel
       ├─ #product / resident ── private Linux VM ── /workspace
       ├─ #finance / resident ── private Linux VM ── /workspace
       └─ #home / resident ───── private Linux VM ── /workspace

Shared host services: model router · connection brokers · audit chain
Per resident: identity · threads · curated memory · Mnemosyne · skills · obligations

Control plane

A Node/TypeScript server owns authentication, SQLite state, REST/WebSocket APIs, model routing, resident execution, channel-computer lifecycle, connection brokers, and background reconciliation. Electron hosts this server on an ephemeral loopback port in the native macOS and Windows apps.

Computers

The Apple backend uses defensive argv-only calls to Apple's container runtime; Linux uses a narrow root-owned LXC helper; Windows uses WSL 2 with one imported distribution per resident. Every production backend enforces exact ownership markers and no host-home exposure. A narrow archive bridge synchronizes the Files UI.

Execution and return

Agent turns are serialized per resident identity. Tools run in the resident's computer unless they belong to the host-brokered capability surface. A resident-origin Skipper escalation records an open escalation; Skipper acts and call_agent returns the thread. The runtime supplies the return when a model omits it.

Memory

Thread summaries remain session records. Curated facts, decisions, preferences, and artifact references retain provenance. Each identity also owns a separate Mnemosyne SQLite store for long-term semantic recall.

Obligations

Follow-ups and machine timers become durable rows. The reconciler wakes due computers and prevents unsafe sleep when services, cron, timers, terminals, active turns, or uncertain state exist.

Providers and connections

The embedded router pools model accounts and exposes one internal gateway. Gmail and Photon are host brokers: residents receive only task-scoped operations and never raw OAuth or project credentials.