MCAStation

Mac Cloud Access Station — a macOS desktop app for managing database tunnels to AWS across projects. SSH bastions today, AWS SSM Session Manager as the migration target.

See docs/bastion-manager-spec.md for the full architecture and the phased roadmap.

Status: Phase 1 — core switcher (SSH)

Implemented:

• SQLite config store (better-sqlite3), projects + environments, seeded with one example project (dev/prod) on first run.
• TunnelManager built on the ConnectionStrategy seam, with SshStrategy live and SsmStrategy stubbed for Phase 3.
• Per-environment state machine (stopped → starting_bastion → bastion_ready → tunneling → connected / error), PID tracking, and kill-all-tunnels on quit.
• TCP health check on the local port.
• Two-pane React UI: project/environment list with phase glyphs + SSH/SSM badges, environment detail with controls, live telemetry, and a log console.

Not yet (later phases): pin-to-5432, Secrets Manager, SSM strategy, generic command runner.

Requirements

• Node 22+ (Electron 43 requires it). Installed here via brew install node@22. See .nvmrc.

Run in development

Node 22 is keg-only, so point at it explicitly (or add it to PATH):

export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
npm start

The first npm start rebuilds the native better-sqlite3 module against Electron's ABI. If it ever gets out of sync (e.g. after upgrading Electron):

npx electron-rebuild -f -w better-sqlite3

Project layout

src/
  shared/     types + IPC contract (spoken by both processes)
  main/       privileged backend — the only place that spawns ssh/aws
    config/   SQLite: db bootstrap, ConfigStore, first-run seed
    tunnel/   ConnectionStrategy, SshStrategy, SsmStrategy(stub),
              TunnelManager, awsService, secret masking
    health/   HealthChecker (TCP probe)
    ipc/      registerHandlers — wires the contract to the services
  preload/    contextBridge — exposes only window.bastion to the UI
  renderer/   React UI (App, EnvironmentForm, PhaseGlyph)

Config location

The SQLite database lives at:

~/Library/Application Support/MCAStation/config.db

Nothing sensitive is stored there — no passwords, no secret values, no bastion IPs (those are fetched live). secret_id is only a pointer into Secrets Manager.