How nateageek/syncreeper works
1. This is a monorepo with two main planes: control and runtime.
The control plane is the user-facing CLI, setup flow, and terminal dashboard. The runtime plane is the Pulumi-managed host configuration plus the sync daemon, Syncthing, and optional reverse SSH tunnel. The repo is organized so the control plane configures the runtime plane rather than replacing it.
2. packages/host is the core infrastructure package.
It contains the Pulumi program that provisions a hardened host in phases, with explicit modules for user and directory creation plus service installation/configuration. The services/ tree is the main architecture boundary: each subsystem is isolated into its own module, and most have Linux/macOS variants under darwin.ts and linux.ts.
3. The host deployment pipeline is layered by responsibility.
The modules indicate a sequence of setup: system packages, firewall, SSH hardening, SSHGuard, auto-updates, GitHub sync, Syncthing, and optional passthrough. This is the primary “infrastructure diagram” axis: base OS hardening first, then repository sync, then peer sync and tunnel features.
4. packages/sync is the repository mirroring engine.
This standalone app handles GitHub repository enumeration and local checkout/update behavior. Its internal boundaries are GitHub API access, git operations, locking, and .stignore generation. The runtime data flow is: GitHub REST API → repository list → local clone/fetch/reset in the repos directory.
5. Repository sync is intentionally incremental and guarded.
The README and sync package structure show that the sync process avoids concurrent runs via a lock file, skips dirty repositories, and uses shallow clone plus fetch/reset for updates. That makes the sync engine a stateful local worker rather than a stateless API client.
6. Syncthing is the distribution layer between devices.
The host package’s Syncthing service module configures the shared folder and device trust model, while the CLI exposes device-management actions. In the overall system, the host sync directory is the source of truth, and Syncthing propagates it to laptops, desktops, and NAS devices peer-to-peer.
7. Security is a first-class subsystem, not an add-on.
The host package separates firewall, SSH hardening, SSHGuard, and auto-updates into distinct modules. The README shows the intent: default-deny inbound rules, key-only SSH, brute-force protection, unattended upgrades, and systemd sandboxing. These are part of the deployment architecture and should be drawn as protective layers around the host runtime.
8. Reverse SSH tunneling is modeled as an optional subsystem.
The passthrough service in packages/host configures the server side, and packages/node-passthrough provides the client-side command set (setup, start, stop, status, uninstall). Architecturally, this is a separate path from the sync flow: it exists to reach a home machine behind NAT through the VPS.
9. The CLI is a thin orchestration layer over host operations.
packages/cli exposes user commands like dashboard, setup, sync-now, get-device-id, add-device, and redeploy. It appears to delegate real system changes to shared host utilities and Pulumi-aware routines, so it should be drawn as a front-end to administration actions, not as the system’s execution core.
10. The TUI is a live monitoring and action surface.
packages/tui is a React/Ink terminal app with tabs for Overview, GitHub Sync, Syncthing, Passthrough, and Security. It polls service status, streams logs, and can issue start/stop/restart actions. In a diagram, it sits above the runtime as an operator console that reads system state and triggers service actions.
11. packages/shared provides cross-package platform abstractions.
This package holds platform detection and shared types used by both CLI and host code. Its presence reflects a core architectural constraint: many behaviors are OS-specific, so common contracts are isolated from platform implementations.
12. Platform branching is central to the design.
The repo explicitly supports Linux and macOS, with separate config, command, resource, and service implementations in packages/host. That means the architecture diagram should show a shared service interface layer feeding distinct OS backends, especially for firewall, SSH, Syncthing, package installation, and auto-update behavior.
13. External dependencies shape the system boundaries.
GitHub is the source of repository metadata and code; Syncthing is the peer sync fabric; Pulumi is the deployment engine; systemd/launchd and UFW/pf provide host integration; SSH/SSHGuard provide access and abuse control. These are not incidental libraries—they define the main runtime and infrastructure boundaries.
14. A useful diagram mental model is: one config source, two execution planes.
Configuration enters through Pulumi and the CLI, then fans out into host provisioning and service runtime. At runtime, the sync service writes to the repos directory, Syncthing mirrors that directory to trusted devices, the TUI observes and controls services, and the passthrough path optionally exposes a separate SSH tunnel service.
Main entry points: services Services · host/src Host · tui/src TUI · sync/src Sync engine
Components 20
Control plane
User-facing orchestration and operator interfaces.
- CLI · Thin command layer for setup, sync, device management, and redeploy actions.
packages/cli/src - TUI · Ink-based terminal dashboard for observing services and issuing actions.
packages/tui/src - Passthrough CLI · Client-side commands for configuring and managing reverse SSH tunnel behavior.
packages/node-passthrough/src
Runtime plane
Pulumi-managed host provisioning and long-running services.
- Host · Core infrastructure package that provisions the hardened host and configures services.
packages/host/src - Config · Shared host configuration, path resolution, and platform-specific constants.
packages/host/src/config - Resources · User and directory provisioning used during host setup.
packages/host/src/resources - Services · Main architecture boundary for host services and OS-specific implementations.
packages/host/src/services - Firewall · Default-deny inbound rules and host firewall configuration.
packages/host/src/services/firewall - SSH · SSH configuration and hardening for key-only remote access.
packages/host/src/services/ssh - SSHGuard · Brute-force protection and ban management for SSH access.
packages/host/src/services/sshguard - Auto-updates · Unattended update configuration and service integration.
packages/host/src/services/auto-updates - GitHub Sync · Host-side repository sync service that pulls code into the local repos directory.
packages/host/src/services/github-sync - Syncthing · Shared-folder replication and device trust configuration.
packages/host/src/services/syncthing - Passthrough · Server-side reverse SSH tunnel support for reaching a host behind NAT.
packages/host/src/services/passthrough - Sync engine · Standalone repository mirroring engine with GitHub access, git operations, locking, and stignore generation.
packages/sync/src
Shared core
Cross-package abstractions and common types.
- Shared · Cross-package platform detection and common types.
packages/shared/src
External systems
Outside services and host integrations that define system boundaries.
- GitHub · Source of repository metadata and code for mirroring and deployment.
- Syncthing network · Device-to-device replication layer for propagating the repos directory.
- Pulumi · Infrastructure orchestration engine for host provisioning.
Pulumi.yaml - OS services · Linux/macOS service managers, firewall tooling, and package management backends.
Connections 27
- CLI → Host: setup / redeploy · CLI triggers host provisioning and deployment routines.
- CLI → Sync engine: sync-now · CLI invokes local repository mirroring actions.
- CLI → TUI: dashboard · CLI exposes the operator dashboard entrypoint.
- CLI → Passthrough CLI: tunnel actions · CLI delegates tunnel setup and lifecycle commands.
- TUI → Sync engine: observe sync · Dashboard reads sync status and logs.
- TUI → Syncthing: observe peer sync · Dashboard monitors Syncthing health and actions.
- TUI → Passthrough: observe tunnel · Dashboard shows passthrough status and controls.
- TUI → Firewall: security view · Dashboard surfaces security-related host state.
- Passthrough CLI → Passthrough: configure client · Client commands manage the local side of reverse SSH tunneling.
- Host → Config: uses · Pulumi program consumes paths and configuration definitions.
- Host → Resources: provisions · Host setup creates users and directories before services.
- Host → Services: installs services · Host program wires the service modules into the deployment.
- Host → Pulumi: runs on · Infrastructure is expressed as a Pulumi program.
- Host → OS services: integrates with · Host modules target platform service managers and system tools.
- Services → Firewall: includes · Service boundary contains firewall hardening.
- Services → SSH: includes · Service boundary contains SSH hardening.
- Services → SSHGuard: includes · Service boundary contains brute-force protection.
- Services → Auto-updates: includes · Service boundary contains unattended update setup.
- Services → GitHub Sync: includes · Service boundary contains repository sync service.
- Services → Syncthing: includes · Service boundary contains peer sync configuration.
- Services → Passthrough: includes · Service boundary contains optional reverse tunnel support.
- GitHub Sync → Sync engine: coordinates · Host service relies on the sync engine for repository mirroring behavior.
- Sync engine → GitHub: reads metadata · Sync engine enumerates repositories from GitHub.
- Sync engine → Shared: uses types · Sync engine shares platform and common types.
- Syncthing → Syncthing network: replicates to · Host-side configuration connects the local folder to peer devices.
- Host → Shared: uses types · Host code relies on shared platform abstractions.
- TUI → Shared: uses types · UI shares platform-aware command and status types.