Declarative orchestration for
2–20 machine clusters
One registry.yml. SSH-only deploys to Docker, uv-managed Python, or native systemd / launchd. A self-healing loop turns recurring failures into reusable playbooks.
+ amd64
What ships today
Each feature below is in the v1.0.0-alpha codebase. Self-healing loop, multi-host SSH orchestration, agentless workers, mixed-architecture support — all live.
Drag & Drop, Then Confirm
Drag services between machines in the web UI. Pending moves stage in a deployment panel — review, then click Deploy. No accidents.
Self-Healing Loop
Every deploy runs through observer → analyzer → solver → learning. When a known failure pattern hits, the matching playbook runs automatically. New fixes are saved to the knowledge base.
Real-Time Monitoring
WebSocket-streamed metrics and deployment logs. CPU, memory, disk, and uptime per service, with custom SVG charts that stay smooth at 1Hz refresh.
Three Deployment Types, One Registry
Run Docker Compose services, local Python apps (uv-managed), and native systemd / launchd services from the same YAML registry.
Security That Actually Ships
mTLS between services with built-in CA distribution, HashiCorp Vault for secrets, and Keycloak OIDC on the backend. SSH-only worker access, no agents.
Dependency Intelligence
Visualize service relationships, analyze change impact, and understand dependencies before deployment.
Root Cause Analysis
Automatic problem diagnosis with suggested fixes. Detects port conflicts, stale processes, disk space issues, and dependency failures.
Deployment History & Rollback
Track all deployments with full audit logs. One-click rollback when things go wrong. Never lose track of changes.
Knowledge Base That Grows
Every resolved problem is recorded as a playbook. Frequency maps surface recurring issues. Your cluster gets smarter as you operate it.
Uptime Tracking
Monitor availability, MTBF, MTTR, and SLA compliance. Detailed event history and analytics included.
Multi-Platform, Mixed Architecture
macOS and Linux. Apple Silicon and Intel. arm64 and amd64 services side-by-side in the same registry, with buildx handling the right platform per host.
MCP-Ready (Preview)
A FastMCP server with a tool registry and audit log is built in. Bring your own MCP tools today; first-party tools land soon.
How it works
Four steps from clone to a deployed cluster.
Clone and bring up the demo
Clone the repo and run the single-machine demo stack. macOS or Linux, Apple Silicon or Intel. No daemons installed on workers.
$ git clone https://github.com/nonagenticai/portoser.git && cd portoser && docker compose upDeclare your cluster
List your machines and services in registry.yml. One file, version-controlled, the source of truth.
$ $EDITOR registry.yml # add machines and servicesDeploy from CLI or UI
Deploy a service with one command, or drag it onto a machine in the web UI and confirm. The self-healing loop runs as part of the deploy.
$ portoser deploy worker-1 my-api # syntax: MACHINE SERVICEWatch it heal itself
Health checks stream over WebSocket. When a deploy fails on a known pattern (port conflict, stale process, disk pressure, dependency unhealthy), the matching playbook runs automatically. New fixes are saved to the knowledge base.
$ portoser cluster health --watchReal Hardware, Real Setups
Four shapes Portoser is actually used in. Pick the one closest to yours — they all share the same registry, CLI, and web UI.
Solo Laptop or Mac mini
1 machine · macOS or Linux · 8–32 GB RAM
Run 5–10 personal services on one box. Get the registry-as-code workflow without cluster setup.
- Single-machine demo mode via docker compose up
- Native systemd / launchd services alongside Docker
- Move to multi-host later without changing your registry
Raspberry Pi Home Lab
3–6 Pis · arm64 Linux · self-hosted
Pin services to specific Pis by role. Build images on a buildx host, deploy over SSH, no agent installs.
- Multi-arch images from one registry.yml
- Caddy auto-reverse-proxies every service
- Self-healing recovers from port conflicts and stale containers
Small Studio Cluster
2× Mac mini + 2× Pi + 1× x86 box
Mixed macOS / Linux, mixed arm64 / amd64. Different services on different hardware roles, one orchestrator.
- Vault for shared team secrets, mTLS between services
- Deployment history with rollback for change control
- Drag-and-drop moves with stage-and-confirm deploys
Home + VPS Hybrid
Local cluster + VPS · mTLS over WireGuard / Tailscale
Run dev on your home cluster, expose public services from a VPS. Same registry, same CLI, same observability.
- Built-in CA distribution to remote hosts
- Caddy-managed TLS at the edge
- WebSocket-streamed deployment logs no matter where it runs
One registry. Every machine.
Self-hosted, agentless, Apache 2.0. Built for homelabs and small teams that want declarative orchestration without a control plane to maintain.