mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-10-25 21:20:25 +00:00
Anso
cee2ec83a6
* fix(blueprints): capture recovery on Pilot apply-local hops The leaf's apply-local route honored allowGitManagedContent and captureRecovery only under the node_proxy machine scope, but a request forwarded through the Pilot tunnel arrives with the agent's pilot_tunnel loopback token. The auth middleware treats the two scopes as the same hub-to-leaf credential and every sibling route already accepts both, so the gate silently dropped the capture and a later rollout rollback on a Pilot target failed with no recovery point to restore. Accept either machine scope for both flags. Browser sessions and API tokens hold neither and are still refused. * fix(gitops): keep a refused rollback from parking the application A rollback a node refused before its restore touched anything was recorded application-wide as a failed recovery. The source facet then read recovery_failed, offered no action, withheld deploys, and stopped polling, while the only exit, a successful restore, was impossible on the refused target. Recovering it took manual row edits. Classify each failed restore by whether it can have mutated the target. The restoring node's own pre/post verdict, attached to the compensation error and carried over the rollback response, wins; otherwise only codes that prove the restore moved nothing are pre-mutation. A pre-mutation refusal is recorded on the target and settles the application restoring stamp in the same transaction, keeping a same-ref completion receipt when another target came back. A 2xx that does not echo the requested generation is its own unconfirmed code and still holds, because the node did restore something unproven. A later successful deploy acknowledgement now retires a stale recovery failure on the acknowledging target and, when no target still reports one, on the application. * docs(blueprints): describe how a refused rollout rollback resolves A target refused before its restore changes anything keeps its visible failure, but it no longer holds the application. The source keeps converging and the next successful deploy to that target retires the stale failure; only a rollback that may have changed a target holds automated work. * fix(gitops): keep rollback holds conservative across retries and refusals A later pre-mutation refusal could erase the application hold an earlier target still needed when that target may have been half-restored: the settle cleared the stamp without checking the other targets, and a retry refused during an unresolved failure overwrote the target's moved class. The settle now restores the hold from a surviving mutated failure, keeps the stamp while any restore is still moving, excludes the refusing targets themselves, and only a pre-mutation refusal defers to an earlier failure's class. A refusal whose own record write throws is settled by the route for every missed target, not just the first. Also carried through the same path: the node's own pre/post classification rides the compensation result and every uncoded refusal (a restore-not-sent outcome for a request that never left the hub, a coded stack-not-found, the self-stack refusal), stack-busy answers hold instead of settling because another operation is moving that stack, a failed mid-write restore whose own revert failed is classified post-mutation, and Enforce runtime repair follows the same pre-mutation release rule. * fix(gitops): derive rollback holds from targets and separate recovery claims The settle no longer keys on one operation's recovery ref: it derives the application phase from the live targets, so two overlapping rollbacks can no longer pin the application in restoring, and the other operation's refusal settles it. The open writes the target's active-operation marker, so a crashed open is selected by boot and reclassified instead of staying restoring, and a missed refusal record is retried for its target rather than only settling the application. The health executor settles a proven refusal whose record throws, the same as the manual route. A recovery hold is now claimed by one shared predicate, targetRecoveryFailureMoved: a failure stage that has moved on no longer claims a recovery, and a pre-mutation refusal never did. The settle, the acknowledgement clearing, and the repair binding use it, and the failure writers clear a superseded recovery phase, so a deploy failure on a refused target cannot re-park the application or re-hold repair. * fix(gitops): retire replaced recovery claims and keep repair behind a retry A deploy failure that replaced a moved recovery failure cleared the target's claim but left the application hold with no claimant, and the acknowledgement's clearing branch then never ran. Claims are now retired through one helper that re-derives the application hold in the same transaction; a successful bind, an acknowledgement and a revived placement retire the claim too, and every rollback terminal retires the recovery_started interruption a crashed open left. Repair checks a restore in flight before the failure claim, so a retry over a refused target holds repair again. A terminal rollback whose recovery ref no longer matches the target changes nothing, a newer rollback open takes over the active marker, and a failed record is retried with the class the attempt was proving for either class. * fix(gitops): keep a moved recovery claim through later failures A recovery claim that may have moved a target was retired whenever a deploy or withdraw failure replaced it, releasing the application hold with nothing proving the target consistent. The claim now keeps its own class in a dedicated column, so a later failure records itself beside the claim instead of overwriting it. Only success evidence (an acknowledgement or a bind) retires a moved claim; a claim that moved nothing is still retired by a later failure. A restore in flight is never rewritten: retirement returns early on capturing, restoring and compensating, and a deploy, withdrawal or acknowledgement terminal that clears its own marker hands it back to the restore so a crash remains boot-recoverable. Superseded terminals are scoped by class: a refusal that moved nothing is a true no-op with no row write, history row or application stamp, while a failure that may have moved the target records its class without touching the newer attempt's phase, ref or marker. rollbackCompleted carries the same ref guard, and the settle re-reads each row after its retry and drops one a newer rollback re-opened. The application hold counts a restoring sibling as a claimant, and a tombstoned target stops answering for the hold it claimed. * fix(gitops): serialize rollbacks per target A second rollback could open over a target whose restore was still running, take over its recovery slot and ref, and leave the application hold released while the first restore was still moving files. One restore per target is now the rule: rollbackInProgress and recoveryStarted refuse a target that is already restoring, the route answers with 409 ROLLBACK_IN_PROGRESS before any restore starts, and the health executor skips its rollback on a target that is already restoring. With overlap impossible, the machinery that arbitrated it is gone: the ref and marker takeover, the skipped-terminal plumbing and the ref guards. A refusal that defers to a moved claim leaves the shared failure slot alone, so a later deploy failure is not relabelled a recovery failure, and the claim keeps its own class and time in dedicated columns. rollbackCompleted, recoverySucceeded and a moved rollbackPartialFailed derive the application stamp from the live targets instead of writing it outright, so one target's outcome cannot release or overwrite a sibling's hold. A restore marker is handed back on every terminal that clears it, including through a tombstone, and both revival paths share one helper. * test(gitops): restore the boot recovery selection test The superseded-terminal tests removed with the rollback serialization also took the boot test that drove the real startup selection, leaving its import unused. Restore it against the current semantics: the open's marker makes the application selectable, boot reclassifies the restore as interrupted, and a later terminal rollback retires the interruption. * fix(gitops): record a terminal when a health rollback hold throws The health executor opened a rollback and then ran the hold and two store reads outside the block that records a terminal. A throw there left the target restoring, and with rollbacks now serialized per target that state refused every later rollback in-process. Everything after the open now lives inside the recording try, so every exit records a terminal; a regression test forces the hold to throw and checks that a later manual rollback is accepted. Boot also selects applications whose own or any target's recovery phase is in flight without an active-operation marker, and records the interruption as recovery_started, so a row an older build left restoring is reclassified instead of being refused for ever. The docs now say every Git-managed rollout deploy captures the node's previous project on every target type, and that a target can have one rollback at a time. Tests removed with the rollback serialization were restored where the behavior still exists. * fix(gitops): stop stamping an application interruption for a recovery Boot reclassification wrote recovery_started into the application's interruption_stage for a marker-less in-flight restore. No recovery terminal clears an application interruption stage, so after any crashed rollback the value stayed for ever, and the drift collectors read a set application stage as a standing suppression while a Direct source deferred its retry. The application row records the interrupted recovery in its recovery phase; the target keeps the operation stage. A regression test reclassifies a crashed rollback and asserts the application stays clearable through a later successful rollback. The route's 409 test now asserts the live rollout authorization and generation are untouched, so a regression that supersedes the rollout before refusing fails the test. The repair test for a refused recovery replaced by a deploy failure now drives the real writers, and the rollback docs no longer claim the source keeps converging. * fix(gitops): keep the poll cadence through a recovery hold A held application settles every evaluation into recovery_required, which armed neither a retry cursor nor a fresh poll. The fetch that ran while the hold stood consumed the poll cursor, so once success evidence cleared the hold the source sat idle: a pushed commit was never fetched and next_poll_at stayed null until the poll interval was saved again. The controller now re-arms the poll for a recovery wait, an in-flight restore or a hold that success evidence retires. Automatic acceptance stays gated on success-shaped outcomes, so the hold still withholds progression. A regression test holds an application through the real rollback writers, consumes the cursor through the real fetch transitions, and asserts the cursor is re-armed. The rollback section of the Blueprint docs again states that every Git-managed rollout deploy captures the node's previous project on every target type.
Self-hosted Docker Compose management for one machine or a fleet.
Docs · Tutorials · Website · Roadmap · Discussions · Sponsor · Buy Me a Coffee
What Sencho is
Sencho is a Docker Compose control plane for DevOps engineers, platform teams, system administrators and homelab users who run services on Compose and need a real operational surface: a graphical interface that does not give up file-on-disk workflows, and the ability to manage more than one machine without SSH gymnastics or a VPN.
It runs as a single container on your hardware and provides a UI for common Compose operations: 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.
Multi-node was part of the architecture from the start, not bolted on later: every Sencho instance is the same autonomous node, whether it runs alone or as one of many in a fleet. 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 an authenticated HTTP and WebSocket proxy across your fleet. Use TLS, a VPN, or a private network for any untrusted link. Each node still uses its local Docker socket (see Quick start), but Sencho does not require SSH and does not expose a remote Docker socket on the network. 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.
Sencho is free, open-source software under AGPLv3. Everything below is included in the Community tier with unlimited nodes and users.
Capabilities
Stacks
- Full Compose lifecycle: create, deploy, restart, stop, take down, pull
- Atomic deployments with automatic rollback on failure
- Monaco editor with diff preview before save and one-click rollback to any prior deploy
- Health-gated updates that hold a rollout until health checks pass, with stalled-update detection and in-app recovery
- Git-sourced stacks pulled and synced from any repository, with ordered multi-file Compose
- File explorer for compose, env, and supporting files, with move and rename across directories
- Drift detection that compares running containers against the effective Compose model and flags exactly what changed
- Environment and secrets guardrails that inventory every variable a stack uses and flag missing or duplicate values, without ever exposing a value
- Storage portability checks that show whether a stack's mounts can move cleanly to another node before you move it
- Compose Doctor preflight checks that catch compose problems before deploy
- Stack labels for grouping and bulk operations
- App Store with LinuxServer.io templates by default, or any custom Portainer-compatible registry
Observability
- Aggregated log search and stream across every container in the fleet
- Live container stats, health checks, and image-update notifications on a configurable cadence, with links from each image to its registry and source
- Threshold alerts for CPU, memory, and network
- Read-only audit log of every action, with a 14-day recent-activity window
- Network topology view of containers, networks, and nodes
- Documentation-drift flags when a stack dossier diverges from the running stack
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
- Fleet Federation: cordon nodes and pin Blueprints to specific hosts
- Fleet Actions: bulk label operations, fleet-wide stop-by-label, and fleet-wide prune
- Fleet Dossier: export the whole fleet as a single browsable Markdown archive
- Fleet Secrets: author environment-variable bundles once, push them to labeled nodes' stacks, with an audit trail of every change
- Fleet Sync: push scan policies, CVE suppressions, and misconfig acknowledgements from a control instance to its replicas
- Docker Label Audit across every node, for labels that drive external automation
- Remote updates: pull the latest image and recreate any node in the fleet from the Fleet view, no SSH session required
- Node labels and grouping
- 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
- Webhooks on stack lifecycle events
- Blueprints: declarative fleet templates with drift detection
Security
- SSO: custom OIDC and presets for Google, GitHub, and Okta
- Two-factor authentication with TOTP and backup codes
- RBAC with five built-in roles and stack or node scoped assignments
- Security overview with a chart-led scan summary, sortable images, and searchable scan history
- Vulnerability scanning via Trivy, with on-demand node-wide scans, VEX-based suppression, SARIF export, and SBOM upload
- Compose network inspector with an exposure-intent guard for unintended published ports
- Node-wide network inventory, topology, and exposure findings across every stack on a node
- Scan policies that set severity thresholds and can block a deploy
- Private registries for Docker Hub, GHCR, and custom registries, plus deploy enforcement for non-compliant images
- API tokens for automation
Operations
- Off-site stack archives via custom S3-compatible storage
- Notification routing to Slack, Discord, and any generic webhook
- Global search across pages, nodes, and every stack in the fleet
- Resources view for images, volumes, and networks with scoped prune actions
- Host console: an interactive terminal on the host OS in the browser, no SSH session required
Before you install
Sencho talks to Docker through the host's /var/run/docker.sock. Mounting this socket grants Sencho the same privilege as sudo docker on the host. This is the same model used by Portainer, Dockge, Komodo, and other Compose dashboards. If your threat model requires stricter isolation, see running with a non-root container user and front Sencho with a reverse proxy that enforces authentication.
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 \
# 1:1 Compose Path Rule: the host path MUST match the container path
-v /opt/docker:/opt/docker \
-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 HTTP and WebSocket requests to the remote instance. The remote node does not run SSH for Sencho, does not expose its Docker socket on the network, and does not run a separate agent process. The local Sencho on each node manages its own Docker through the standard socket mount described in Quick start. 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
 |
 |
 |
 |
 |
 |
 |
 |
Same screens in OLED
 |
 |
 |
 |
 |
 |
 |
 |
Same screens in Light
 |
 |
 |
 |
 |
 |
 |
 |
Telemetry and data handling
Sencho does not emit telemetry, analytics, or crash reports, and makes no outbound calls to Sencho-controlled endpoints. Stack metadata, container inventory, and user activity never leave your instance.
Admiral
Admiral is Studio Saelix's paid business assurance plan on top of everything in Community: Hardened Build, Recovery Vault (managed off-site snapshots), priority support, and governance depth (LDAP / Active Directory, full audit log export and anomaly detection, and related organizational controls). Built-in RBAC (five roles and scoped assignments) is included on Community. AWS ECR registry credentials currently require Admiral as well; that access rule is temporary availability, not the reason Admiral exists. See sencho.io/pricing for current plan details.
Documentation, community, and license
- Documentation: docs.sencho.io
- Blog: sencho.io/blog
- If something breaks: the Recovery guide covers getting back to a working state when Sencho, a deploy, sign-in, Docker, or a node fails.
- Community: GitHub Discussions
- Contributing: CONTRIBUTING.md
- Security: SECURITY.md. Do not open public issues for security vulnerabilities.
- License: GNU Affero General Public License v3.0 (
AGPL-3.0-only). Copyright (c) 2026 Studio Saelix. Sencho is free software; see LICENSE and Licensing for terms. Studio Saelix trademarks are described in TRADEMARKS.md.