Anso
da905ab07c
* refactor(gitops): split source acceptance from Direct target application applied() bound source acceptance and Direct target application in one mutation, so a future dispatch path could not accept a candidate and defer binding a target until after promotion. Extract the mode-neutral and Direct-only mutations into shared helpers, and expose them as sourceAccepted and targetApplied. applied() now composes the same helpers in the same transaction and emits the same single history row, so its observable contract is unchanged. targetApplied refuses to bind a target to a generation the application has not accepted, so a target can never be bound to source content nothing authorized. * fix(gitops): move apply's cache invalidation and post-deploy scan into the service invalidateNodeCaches and triggerPostDeployScan were called by the manual apply route only, so a webhook-driven apply (and any future poll, retry, or resume trigger) never invalidated caches or ran a post-deploy scan. Move both into GitSourceService.apply() itself: cache invalidation fires once whenever promotion commits, apply-only and deploy-failed outcomes included, since the authoritative Compose files have already changed by then regardless of whether a deploy followed; the post-deploy scan still fires only after a successful deploy. Remove the now-redundant calls from the apply route so each still runs exactly once. * feat(gitops): add tri-state candidate policy evaluation The deploy-time policy gate deliberately fails open (ok: true, trivyMissing: true) when the scanner is unavailable, so an operator is never blocked from deploying. That fail-open behavior must not extend to automatic GitOps source acceptance: an unresolvable scanner state accepting a candidate nothing actually proved safe would defeat the policy gate entirely. Add evaluateCandidatePolicy, a thin tri-state (allowed | blocked | unavailable) wrapper around the existing enforcePolicyForImageRefs evaluator. It takes the candidate's own image refs directly rather than reading compose from disk, so a future caller evaluating a staged candidate (before it is promoted to the live stack) can reuse the same policy logic the deploy gate already uses. * feat(gitops): propagate the raw transport failure reason onto GitSourceError The native transport catch block classified a raw TransportFailure into a sanitized (code, message) pair for GitSourceError, discarding the structured reason (e.g. exit, timeout, target-unresolved) once it had been logged. A future GitOps retry/backoff classifier needs more than the public error code to tell a transient network condition from a permanent configuration one, since several distinct reasons collapse onto the same code (both a DNS failure and a connection reset map to NETWORK_TIMEOUT, and several permanent conditions map to GIT_ERROR). Add transportReason to GitSourceError.extras, carrying the original reason through both throw sites. * fix(gitops): give source suspension its own reason field sourceSuspended and sourceUnsuspended wrote and cleared pause_reason, the same column rolloutPaused and rolloutUnpaused use on the application row. Suspending a source and later pausing its rollout (or the reverse) would silently overwrite whichever reason was written first, since both events share the row but were sharing one field for two unrelated concerns. Add a distinct source_suspended_reason column, move sourceSuspended and sourceUnsuspended onto it, and surface it on the source_suspended projection facet so a suspended source's reason is visible independently of any rollout pause reason on the same application. * feat(notifications): add a GitOps operation reference and dedupe key notification_history had no way to link a notification back to the GitOps history/operation it reports on, and no way to detect a duplicate: it has only an autoincrement id and an unstructured message. A future GitOps fanout repair (re-running after a crash between a settled attempt commit and its notification) needs to be idempotent, which the table could not support. Add gitops_operation_id and dedupe_key columns, with a partial unique index on dedupe_key so a second insert with the same key is a no-op returning the existing row rather than a duplicate notification. Both columns are optional and every existing caller is unaffected: omitting dedupe_key keeps today's behavior exactly. * feat(gitops): classify suspend/resume/retry as stack:edit for remote routing An unclassified named-stack path fails closed with 403 on a remote node, so a future suspend/resume/retry endpoint would be unreachable there until its classification landed. Add the three suffix rules now, matching the existing git-source/pull and git-source/apply entries, so remote and scoped-permission routing already works correctly once those endpoints are added. * fix(gitops): address pre-commit review findings on the acceptance split Code review found five substantive issues across the prior six commits: - targetApplied took applicationId as a redundant positional parameter alongside AppliedArgs.applicationId, which every caller had to pass twice; the copy inside args was silently ignored. Drop the positional parameter. - targetApplied had no target_mode guard, unlike applied()'s existing Direct-only check, so a Blueprint target could in principle be bound through it. Add the guard. - The frontend's hand-written GitOps type mirror was not updated for the new suspendedReason field, which the file's own header warns is exactly the drift it does not detect on its own. - The dedupe unique index's creation failure was silently swallowed, but unlike a pure performance index, this one is the ON CONFLICT target every notification write depends on; a missing index would break every notification in the product with no diagnostic. Log it. - evaluateCandidatePolicy inherited the deploy-shaped default audit path from the evaluator it wraps, so a bypassed candidate evaluation would write an audit row claiming a deploy that never happened. Default the audit attribution to a candidate-evaluation path before delegating. Also: removed a test fixture in git-source-routes.test.ts duplicating the shared one in helpers/gitopsFixtures.ts, hoisted the repeated policy field out of CandidatePolicyEvaluation's union, and removed an unnecessary any cast. * fix(gitops): close three safety gaps found in the pre-merge audit An independent audit of PR #1892 found three release-blocking defects in the source acceptance split, each reproducible against the existing test suite: - sourceAccepted() accepted a candidate while its source was suspended. applied() (preserved byte-identical, predating suspension) shares this gap, but the plan's own suspension guarantee is specifically for the new entry point, so the check is added to sourceAccepted() directly rather than the shared guard applied() also uses. - evaluateCandidatePolicy() misclassified three safety cases: an image reference that failed validation was silently skipped and read as allowed; a scanner execution failure was treated as a genuine policy violation (blocked) rather than an inability to evaluate (unavailable); and an explicitly authorized bypass still returned unavailable when the scanner was absent, since that early-return path in the shared evaluator ignores the caller's bypass flag. Fixed by requesting fail-closed handling of invalid refs from the existing evaluator, distinguishing a genuine scanned violation from an evaluation failure by whether the violation carries an `error` field, and honoring bypass before returning unavailable. - targetApplied() validated only that its generation was still the application's accepted one, not that the target's own candidate still matched it or that the supplied acceptance reference was the one actually recorded. A delayed dispatch of a since-superseded (but still accepted) generation could erase a newer candidate already staged on the target, and a caller could bind a target to a nonexistent acceptance reference. Both are now validated before mutation. Also removed two explicit `any` callback parameters the audit flagged in the new dedupe test, typing the array instead so inference covers them.
Self-hosted Docker Compose management for one machine or a fleet.
Docs · Tutorials · Website · Roadmap · Discussions · Sponsor · Buy Me a Coffee
Note
Sencho is used in production for day-to-day Docker Compose and fleet management. As a pre-1.0 project it still evolves quickly, so review the known limitations and validate against your own setup before deploying it on critical infrastructure.
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
- Known limitations: KNOWN_LIMITATIONS.md
- 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.