Why Portoser
Declarative orchestration for the cluster you already have
Portoser is built for clusters of 2 to 20 machines — often mixed-architecture (Apple Silicon, Intel, Raspberry Pi) and mixed-OS (macOS and Linux). One declarative registry, SSH-based deploys, no agents on workers, and no control plane to maintain.
What Portoser is
A single declarative registry (registry.yml) that defines:
- The machines in your cluster
- The services running on them
- Health checks, dependencies, environment, and secrets
…driven by a Bash + Python toolchain that:
- Deploys via SSH (no worker agents)
- Supports three deployment types from one registry — Docker Compose, local Python (uv), and native systemd / launchd
- Runs a self-healing loop (Observe → Diagnose → Solve → Standardize) on every deploy
- Exposes a web UI for drag-and-drop service moves, health, metrics, history, Vault, and certificates
- Includes an MCP server so AI assistants can register tools that operate on the cluster
What Portoser is not
Not Kubernetes
No CRDs, operators, etcd, or overlay network.
Not A PaaS
It does not build your code or run autoscalers.
Not For cloud-scale
Built and tested for clusters of roughly 2–20 hosts.
Not A hosted product
You run it on your own machines.
Compared to other tools
| Tool | Where Portoser differs |
|---|---|
| Kubernetes (K3s / k0s / microk8s) | K3s installs in minutes. The cost is everything after — control plane, ingress controllers, RBAC, manifest drift. Portoser stays in YAML and Bash you can read. |
| Nomad | Lighter than Kubernetes but still a scheduler with agents on every worker. Portoser is agentless and declarative-first. |
| Coolify / CapRover | Single-host or git-push focused. Portoser is multi-host and registry-first — the source of truth is checked into your repo. |
| Portainer | A web UI on top of Docker. Portoser includes a UI too, but the source of truth is registry.yml in version control, not the UI's database. |
What actually ships
Verified against the codebase as of v1.0.0-alpha. Each item points at the code that implements it.
Agentless multi-host orchestration over SSH
lib/cluster/
Three deployment types
lib/docker.sh, lib/local.sh, lib/native.sh
Self-healing loop
lib/observe/, lib/diagnose/, lib/solve/, lib/standardize/
Knowledge base of resolved problems
~/.portoser/knowledge/playbooks/
Caddy auto-config with live admin-API reload
lib/caddy_integration.sh
mTLS with built-in CA distribution
install_ca_on_hosts.sh
HashiCorp Vault integration
with a Portoser-built management UI
Web UI
cluster view, drag-and-drop, dependency graph (ReactFlow), monitoring, history with rollback, certificates, Vault, MCP tool registry
WebSocket-streamed deployment logs and metrics
real-time, no polling
500+ tests across the CLI and web backend
including security and race-condition coverage
What's still cooking
If we listed it on the homepage, we'd be lying. Here's what's not done yet.
First-party MCP tools
The FastMCP server and tool-registry API are wired. First-party tools that act on the cluster land soon. You can register your own today.
Frontend Keycloak login flow
Backend OIDC middleware is ready. The web UI's login page is in progress.
CI matrix for multi-host scenarios
Multi-host paths are tested locally. CI matrix coming.
Who Portoser is for
- Solo developers running side projects across a Mac mini and a couple of Pis.
- Small studios with a handful of machines they want to treat as one cluster.
- Home-lab operators who want declarative orchestration without a control plane to maintain.
- ML engineers splitting CPU services and a single GPU box.
- AI developers experimenting with letting an MCP-equipped assistant run their cluster.