Sage is a lightweight single-user micro-PaaS for running and managing Docker-based applications across a small set of machines. It uses Tailscale for node connectivity, Cloudflare for domains, DNS and public apps, Traefik for ingress, and a web UI for day-to-day operations.
Detailed technical and development-oriented material lives in docs/.
Sage is built around a manager node that coordinates one or more worker nodes over a private Tailscale network.
- The manager provides the API and web UI.
- Workers run application containers and supporting edge services.
- Cloudflare provides the domain: DNS, a tunnel on each worker for public apps, and the DNS-01 validation for Let's Encrypt certificates.
- Traefik on each worker routes its names to its own containers.
- Metrics and logs are collected centrally for visibility and troubleshooting.
- Backups can be stored with S3-compatible object storage.
Sage is designed for small, practical self-hosted deployments rather than large-cluster orchestration.
At a high level, Sage has three main layers:
- A manager service that stores platform state, coordinates deployments, and exposes the UI and API
- Worker nodes that run applications, ingress, and supporting runtime services
- Shared platform integrations for networking, DNS, metrics, logs, and backups
The manager-to-workers model over Tailscale is the core operating pattern.
For deeper architecture details, see docs/architecture.md.
- Manage projects, applications, containers, domains, volumes, workers, settings, backups, and notifications
- Deploy applications from Docker images or Git repositories (private repos via a
GIT_AUTH_TOKENbuild secret) - Stop and delete deployed workloads
- Route public and internal traffic through generated Traefik configuration
- Add workers from your tailnet and bootstrap them over Tailscale
- Collect worker and container metrics
- Ingest and search container logs
- Create and restore platform and application backups
The manager is a single container image, ghcr.io/v31-dev/sage. It runs anywhere that
runs a container with a persistent volume. It joins your tailnet as its own node, so it
needs no published ports, public URL, host Tailscale or TUN device.
It needs:
TS_AUTH_KEY— a Tailscale auth key for the manager's node. Create it tagged (the tag becomes the manager's tag) and not ephemeral. It is only used while the node has no tailnet identity yet (first boot, or after its state is lost). If the node can't join the tailnet with it (an invalid or expired key), the container exits at once with a[CRITICAL]line.TS_NAME— the manager's tailnet machine name, also its name inside Sage.DOMAIN— a domain whose DNS is on Cloudflare: its zone must be active (the registrar lists Cloudflare's nameservers). Apps get addresses under it, and the UI is served only athttps://<TS_NAME>.core.<DOMAIN>.CLOUDFLARE_API_TOKEN— a user API token, created under My Profile › API Tokens (account-owned tokens are not supported), with Account › Cloudflare Tunnel › Edit and Zone › DNS › Edit, and nothing else. Limit it to the account and to the one zone ofDOMAIN. It must see only one active zone forDOMAIN; Sage uses the account that holds that zone.ENCRYPTION_KEY— encrypts secrets in the database, platform backups and volume backups. Generate one withopenssl rand -base64 32 | tr '+/' '-_'and keep it with your S3 credentials: backups can't be restored without it. It can't change after the first boot: Sage refuses to start with a different key. To use another key, wipe the volume and start again. Restoring a backup needs the key it was made with, so recovering onto a new volume means starting with the original key.- A persistent volume at
/app/data. - Exactly one running instance.
- A stop grace period of a few minutes. On a stop signal Sage starts no new work and lets running tasks (a deploy, a backup) finish before it exits. Docker's default is 10 seconds before it kills the container.
.env:
TS_AUTH_KEY=tskey-auth-...
TS_NAME=sage
DOMAIN=example.com
CLOUDFLARE_API_TOKEN=...
ENCRYPTION_KEY=...Leave the values unquoted: docker run --env-file keeps quotes as part of the value.
With docker run:
docker run -d --name sage --restart unless-stopped --stop-timeout 300 \
--env-file .env \
-v sage-data:/app/data \
ghcr.io/v31-dev/sage:latestWith Docker Compose:
services:
sage:
image: ghcr.io/v31-dev/sage:latest
restart: unless-stopped
stop_grace_period: 5m
env_file: .env
volumes:
- sage-data:/app/data
volumes:
sage-data:latest follows the newest release. Pin a release tag (ghcr.io/v31-dev/sage:<version>,
see the GitHub releases) to control when you upgrade.
On start, before serving anything, Sage sets up Cloudflare (the platform's tunnel and the manager's DNS record) and gets the manager's certificate from Let's Encrypt. A first start can take a few minutes. If Cloudflare is unreachable or answers with a server error, Sage retries for about 20 minutes and then exits, and its log says why. A token Cloudflare rejects, or a domain the token can't use, exits at once with the reason. With a certificate from an earlier start, it serves even while the Cloudflare setup fails.
unless-stopped restarts Sage after a crash and after a host reboot, without limit. A
start that keeps failing then loops, which Let's Encrypt tolerates: failed validations are
capped at 5 per hour, Sage stops immediately once it is rate limited, and Let's Encrypt
doesn't ban addresses. If you'd rather it give up, restart: on-failure:5 (--restart on-failure:5) stops after 5 failed starts, but Docker doesn't restart on-failure
containers after a host reboot, so you then start Sage by hand.
Enable MagicDNS: the manager reaches workers by name. The UI's address,
<TS_NAME>.core.<DOMAIN>, is a Cloudflare DNS record pointing at the manager's tailnet
IP, so it only works from the tailnet. Plain http://<TS_NAME> redirects to it.
Sage has no login or access control of its own. Anyone who can reach the manager over the tailnet can use the UI and API, including reading the stored S3 keys and Discord webhook. The tailnet policy is the only gate: restrict who can reach the manager, and never expose it outside the tailnet (no published ports, no public URL).
In the tailnet policy, give the manager and the workers their own tags (the examples use
tag:sage and tag:sage-worker) and allow the traffic Sage uses. Anything not allowed is
unreachable; tailnet traffic reaches every port the manager container listens on.
A worker is a Linux machine with Docker (including the Compose plugin) that joins the tailnet with Tailscale SSH enabled:
tailscale up --ssh --auth-key=tskey-auth-... # a key tagged tag:sage-workerThe tag is for the tailnet policy above, which lets the manager reach the machine; Sage does
not read it. Add the machine on the Workers page by its hostname or Tailscale IP: Sage checks
that it answers, then sets it up over SSH. In Sage a worker has a subdomain, given when
it is added, which its internal names are under (<name>.<subdomain>.int.<DOMAIN>). A new
worker gets its own certificate and private key; changing its subdomain replaces only that
certificate. Workers share a separate certificate for internal discovery. Certificates use
45-day validity and renew with seven days remaining. The worker's page shows each certificate's
status and applied expiry separately; Settings → Cloudflare shows the full inventory and any issuance or
retirement errors. See Certificate Lifecycle for cleanup and rate limits.
Deleting a worker stops
Sage's services on it and removes Sage's files from it. A worker with containers or internal domains can't be
deleted: delete its containers and move or delete its domains first, even when it is offline. A worker that is
offline is removed from Sage only; its VM has to be cleaned up by hand.
A worker records which Sage manages it. Several Sages can share a tailnet when each has its own domain, S3 path and workers: a machine that another Sage manages is refused, and has to be deleted from that Sage first. Give each Sage its own tags in the tailnet policy if one must not reach the other's workers.
Workers are meant to be dedicated to Sage: a hardened, bare VM with Docker and nothing else running on it. The manager has no such requirement; it needs only Docker and runs anywhere, on a laptop, a PaaS or a VM.
Sage is meant for one domain with about 10 workers and 50 applications; another domain or landscape runs its own Sage. The smallest recommended machine, for the manager and for each worker, is 1 GB of memory and 1 core. Give a machine more as its applications and logs grow.
Once Sage is up, the UI is at https://<TS_NAME>.core.<DOMAIN>. S3 (backups) and
notifications are optional and set in the UI.
An application is reached at the names you give its containers on the Domains page: a public
name <name>.<DOMAIN>, or an internal one <name>.<subdomain>.int.<DOMAIN> (tailnet only, on
its worker). Names that share a service are listed together for clients that choose one, at
https://discovery.<DOMAIN>/?service=<service> (public) or
https://discovery.int.<DOMAIN>/?service=<service> (internal), in the Sage-Endpoints
header, with an online flag for each name; Domain Types has the details.
Each HTTP Domain can allow frontend origins for browser API requests.
The client guide shows how to discover a backend service, probe its replicas and choose one.
Sage lists the backups already in the S3 bucket and path when you save the S3 settings,
at startup and from Discover backups on the Backups page. To recover onto a new volume,
start with the original ENCRYPTION_KEY, set S3, then restore a platform backup; volume
backups are listed once their application is back. A platform restore replaces the configuration
with the backup's, keeps the S3 settings in use and starts the history empty. Containers are then
stopped and show an error until they are deployed again, also when the workers kept serving while
the manager was being recovered, and a container that isn't in the backup is removed from its worker
with its volumes' data; see Platform Backup And Restore.
Each backup can also be downloaded
from the Backups page (platform) or a volume's Restore dialog (volume): a link that works
for a minute, straight from S3. The files are encrypted; Settings → S3 shows how to open one.
To change TS_NAME or the Cloudflare details, edit the env and restart:
Sage brings the workers in line on start. A new TS_NAME renames the manager's tailnet
machine, and the manager's metrics history starts over. Records and tunnels of a previous
domain, account or name stay in Cloudflare until you delete them; they are listed in
Cloudflare Resources.
See DNS and API limits for Cloudflare's quotas and how Sage reports failures.
Sage doesn't upgrade itself. The version in the footer opens Settings → Upgrade, with the release notes and the steps: take a backup, pause Sage and wait until it is safe to stop, then run the newer image against the same volume. Sage always starts unpaused. The backup comes first because a paused Sage refuses changes and starts no tasks.
The newer version migrates the data when it starts, from 0.1.3 or any later release; an older
install runs 0.1.3 once first. If the migration fails, Sage stops and leaves the data as it was,
so the previous version still runs on it, and Settings → Upgrade → Migration logs shows why. Once migrated, the data no longer opens in an earlier
version: going back means restoring the backup, or putting back the copy of the database Sage
took before migrating, data.db.migration-<version> in the data folder, kept 90 days.
The repo's docker-compose.yml and sample.env are
for local development; see docs/development.md.
{ "tagOwners": { "tag:sage": ["autogroup:admin"], "tag:sage-worker": ["autogroup:admin"] }, "acls": [ // Your devices → the manager UI (443; 80 only redirects to it) {"action": "accept", "src": ["autogroup:member"], "dst": ["tag:sage:80,443"]}, // Workers → the manager: Telegraf's reports and Vector's logs {"action": "accept", "src": ["tag:sage-worker"], "dst": ["tag:sage:9001"]}, // Manager → workers: SSH (Tailscale SSH) {"action": "accept", "src": ["tag:sage"], "dst": ["tag:sage-worker:22"]}, // Internal and TCP app domains (*.<subdomain>.int) and internal discovery, served by workers {"action": "accept", "src": ["autogroup:member", "tag:sage-worker"], "dst": ["tag:sage-worker:443,8443"]} ], "ssh": [ // Tagged sources must use "accept" (not "check") {"action": "accept", "src": ["tag:sage"], "dst": ["tag:sage-worker"], "users": ["root"]} ] }