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 computer ── /workspace
       ├─ #finance / resident ── private Linux computer ── /workspace
       └─ #home / resident ───── private Linux computer ── /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 Podman helper. Windows enters the same helper inside one installation-scoped managed WSL runtime. Every ordinary channel still owns one distinct persistent container, filesystem, process tree, hostname/network identity, and resource limits. OCI Files/Cowork access runtime-owned storage directly.

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 exists.

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.