mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 11:49:16 +00:00
Anso
f5a52e44dc
* refactor(pilot): narrow PilotTunnelManager.getBridge to MeshTunnelHandle
The manager handed out the entire PilotTunnelBridge to its only consumer,
MeshService, which let any current or future caller reach into transport
internals: loopback URL, per-stream maps, the close API, the underscored
_writeTcpData / _closeTcpStream, the diagnostic helpers. None of that
was load-bearing for Mesh.
Introduce a MeshTunnelHandle interface alongside TcpStream in
PilotTunnelBridge.ts that exposes only the two methods Mesh actually
calls (openTcpStream and getBufferedAmount), have PilotTunnelBridge
declare implements MeshTunnelHandle, and change getBridge to return
the interface. MeshService continues to compile unchanged because its
existing call sites only touch the narrowed surface.
A future alternative transport (a stub for tests, a different routing
strategy) now has a one-method-and-a-getter contract to satisfy
instead of the full bridge.
* refactor(pilot): drop unused tunnel manager and bridge surface
Three public methods predating the hardening pass had zero callers
across the entire codebase (verified via grep across backend, frontend,
e2e):
- PilotTunnelManager.touch(nodeId): never invoked. The pilot_last_seen
timestamp is updated by the manager itself on registerTunnel and by
the persistence layer on heartbeat events.
- PilotTunnelManager.listActive(): never invoked. The metrics endpoint
added in PR #979 returns its own per-node breakdown via
getMetricsSnapshot, which is the canonical observability surface.
- PilotTunnelBridge.listTcpStreams() and the supporting
TcpStreamSummary interface: never invoked. The Mesh diagnostics
sheet that would have consumed it is not wired and would use
getMetricsSnapshot if/when it ships.
Removing them tightens the public surface and prevents accidental new
dependencies on speculative future-proofing.
* test(pilot): cover enrollment replay rejection at the route layer
The DB-level test in pilot-enrollment.test.ts already verifies that
consumePilotEnrollment is one-shot. That guards the persistence layer
but not the route handler: a refactor of handlePilotTunnel that swaps
the order of consume vs upgrade, or that grants the WebSocket
upgrade before checking the consume result, would silently break the
security invariant while DB-layer tests stay green.
Drive handlePilotTunnel directly with a stub IncomingMessage and
Duplex socket. Six cases:
- Already-consumed enrollment row -> 401.
- Token whose hash matches no row -> 401.
- Row whose expires_at has passed -> 401.
- Missing Authorization header -> 401.
- JWT signed with a wrong secret -> 401.
- pilot_tunnel JWT for an unknown node -> 404.
The stub captures HTTP/1.1 status writes so the test asserts the
exact rejection lands on the wire, not just that the function
returned without throwing.
* docs(debug): warn future committers off per-frame isDebugEnabled calls
Code-review feedback on PR #979 noted that isDebugEnabled is fine in
the cadences it has today (per-tunnel, per-request, error paths) but
is fragile against a future commit that drops it into a per-frame
WebSocket loop. The function does a try/catch + Node require cache
lookup + a method call into DatabaseService on every invocation;
acceptable at hundreds of calls per second, expensive at thousands.
Add a comment block above the function spelling out the acceptable
and unacceptable cadences and the snapshot-outside-the-loop
mitigation, so the next person to add a diag log there sees the
constraint.
* fix(pilot): address PR A code-review findings
Code review on this branch surfaced four items:
- Em-dash directive (CLAUDE.md Directive 18) violations in four
comment sites; replaced with colons or restructured.
- debug.ts perf comment claimed try/catch frame setup as the cost
driver. V8 inlines those; the load-bearing cost is the require
lookup and singleton dispatch. Reword.
- Test file header described coverage as 'replay rejection at the
route layer' but the file now also covers missing-header,
wrong-secret, expired-row, never-stored, and unknown-node
rejection paths. Widen the JSDoc and the describe label to match.
- Stub-cast comment in the replay test now explicitly lists the
IncomingMessage and Duplex surface the stub satisfies, so a
future commit that grows handlePilotTunnel's surface (rate
limiting, socket options) updates both stubs instead of
silently no-opping against them.
No behavior change.
Self-hosted Docker Compose management for one machine or a fleet.
Docs · Website · Discussions · Sponsor
What Sencho is
Sencho is for homelab operators, small DevOps teams, and platform engineers who run services on Docker Compose, want a graphical interface without giving up file-on-disk workflows, and need to manage more than one machine without SSH gymnastics or a VPN.
It runs as a single container on your hardware and gives you a UI for the work you currently do over SSH on compose stacks: deploying, editing files, watching logs, restarting containers, browsing volumes, and recovering from failures. Your compose files stay on the host filesystem and remain the source of truth.
A Sencho instance is autonomous. To manage another machine, you install a second Sencho on it and connect them with a long-lived API token; the primary dashboard then acts as a transparent HTTPS proxy across your fleet. There is no SSH and no exposed Docker socket. For nodes behind NAT or strict firewalls, the Pilot Agent establishes a single outbound WebSocket tunnel to the primary, so the remote host opens no inbound port at all.
Most capabilities are free in the Community tier. A few advanced automation and fleet-control features ship in paid tiers; pricing lives at sencho.io/pricing.
Capabilities
Stacks
- Full Compose lifecycle: create, deploy, restart, stop, pull
- Monaco editor with diff preview before save and one-click rollback
- Git-sourced stacks pulled and synced from any repository
- File explorer for compose, env, and supporting files
- Stack labels for grouping and bulk operations
- App Store with LinuxServer.io templates
Observability
- Aggregated log search and stream across every container in the fleet
- Live container stats, health checks, and image-update notifications
- Threshold alerts for CPU, memory, and network
- Read-only audit log of every action
- Network topology view of containers, networks, and nodes
Fleet
- Multi-node management via authenticated HTTP and WebSocket proxy
- Fleet view with grid and topology layouts
- Fleet snapshots of compose and env across the fleet
- Pilot Agent for nodes behind NAT or strict firewalls
- Node compatibility checks before deploying
Automation
- Auto-heal policies for failed containers
- Auto-update policies for image rollouts
- Scheduled operations on cron
- Blueprints: declarative fleet templates with drift detection
- Webhooks on stack lifecycle events
- Encrypted Fleet Secrets pushed to labeled nodes
Security
- SSO: custom OIDC, presets for Google, GitHub, and Okta, plus LDAP and Active Directory
- Two-factor authentication with TOTP and backup codes
- RBAC with admin, editor, and viewer roles
- Vulnerability scanning via Trivy with VEX-based suppression and SARIF export
- Private registries and deploy enforcement for non-compliant images
- API tokens for automation
Operations
- Host console in the browser
- Sencho Cloud Backup for off-site stack archives
- Notification routing to Slack, Discord, email, and webhooks
- Global search across stacks, containers, and services
- Resources view for images, volumes, and networks with scoped prune actions
Quick start
Sencho runs in a single container.
services:
sencho:
image: saelix/sencho:latest
container_name: sencho
restart: unless-stopped
ports:
- "1852:1852"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./data:/app/data
# 1:1 Compose Path Rule: the host path MUST match the container path
- /opt/docker:/opt/docker
environment:
- COMPOSE_DIR=/opt/docker
- DATA_DIR=/app/data
docker compose up -d
Open http://your-server:1852 and create your admin account.
Always front Sencho with a TLS-terminating reverse proxy in production. See the self-hosting guide for hardening, environment variables, and reverse-proxy examples.
Run with docker run instead
docker run -d --name sencho \
-p 1852:1852 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v sencho_data:/app/data \
-e COMPOSE_DIR=/opt/docker \
saelix/sencho:latest
For the full walkthrough, see the quickstart guide.
Adding remote nodes
To manage a second machine, install Sencho on it the same way, then add it from the primary dashboard with its URL and a long-lived API token. The primary proxies authenticated HTTPS and WebSocket requests to the remote instance. No SSH, no exposed Docker socket, no agent process on the remote. Nodes behind NAT or strict firewalls can opt into the Pilot Agent for outbound-only connectivity.
See the multi-node guide for the full token-bearer flow.
Screenshots
 |
 |
 |
 |
Documentation, community, and license
- Documentation: docs.sencho.io
- Community: GitHub Discussions
- Contributing: CONTRIBUTING.md
- Security: SECURITY.md. Do not open public issues for security vulnerabilities.
- License: Business Source License 1.1. Free for production use; the only restriction is offering Sencho as a competing hosted or managed service. Converts to Apache 2.0 on 2030-03-25.