HeyPuter Fleet

Overview

Four independent self-hosted HeyPuter instances run as Docker Compose stacks on auxserver-prod. Each stack is a full Puter deployment (desktop OS, API, file storage, optional local LLM).

Field	Value
Image	ghcr.io/heyputer/puter:26.05.2 (pinned)
Instances	4 (instance1–instance4)
Live path	~/puter/instanceN
Desktop URL	https://puterN.cadenceworks.tech (N=1..4)
Local ports	4101–4104 (nginx → Caddy)
TLS	Caddy (/etc/caddy/Caddyfile)
Internal proxy	nginx per instance (HTTP only)

Full operator guide: [~/puter/README.md](file:///home/ty/puter/README.md)

Use the apex domain (puterN.cadenceworks.tech) for the OS desktop — not site.puterN.* (user static hosting).

Instance Matrix

Instance	Compose path	Host port	Apex domain	Ollama
1	~/puter/instance1/	4101	puter1.cadenceworks.tech	enabled
2	~/puter/instance2/	4102	puter2.cadenceworks.tech	enabled
3	~/puter/instance3/	4103	puter3.cadenceworks.tech	disabled
4	~/puter/instance4/	4104	puter4.cadenceworks.tech	disabled

Architecture

Browser → Caddy :443 → localhost:410N → nginx :80 → puter:4100
                                              └─ s3.* → rustfs :9000

Each instance stack: valkey, mariadb, dynamo, s3 (+ s3-init), puter, nginx. Ollama is optional (docker compose --profile ai up -d) on instances 1–2 only.

Docker Compose

Paths: ~/puter/instance1/docker-compose.yml … instance4/docker-compose.yml

Fleet upgrade script: ~/puter/upgrade-instances.sh

# Pin image across all instances (default tag: 26.05.2)
bash ~/puter/upgrade-instances.sh

# Override base directory or tag
PUTER_IMAGE_TAG=26.05.2 PUTER_BASE_DIR=~/puter bash ~/puter/upgrade-instances.sh

After any puter container recreate, restart nginx in that instance:

cd ~/puter/instanceN && docker compose restart nginx

Environment Variables

Secrets are in instanceN/.env and instanceN/puter/config/config.json. Do not copy values into docs.

Variable / file	Purpose
HTTP_PORT	Host port for nginx (4101–4104)
MARIADB_*	MariaDB credentials — must match config.json → database
S3_*	RustFS credentials — must match config.json → s3.s3Config
config.json	Domains, JWT secrets, redis/dynamo/s3 endpoints, trust_proxy, subdomain_offset

Key Configuration

• Image pin: 26.05.2 — avoid :main and 26.06.2
• trust_proxy: 2 — Cloudflare + Caddy proxy chain
• subdomain_offset: 3 — three-level domain (puterN.cadenceworks.tech)
• Caddy sets X-Forwarded-Proto: https and X-Forwarded-Port: 443
• Persistent data: ~/puter/instanceN/puter/data/ (mariadb, valkey, dynamo, s3, ollama)
• TLS terminates at Caddy; compose nginx HTTPS is disabled

Subdomains (per instance N)

Hostname	Purpose
puterN.cadenceworks.tech	Desktop OS (apex)
api.puterN.cadenceworks.tech	REST / WebSocket API
site.puterN.cadenceworks.tech	User static hosting
host.puterN.cadenceworks.tech	Alt static hosting
app.puterN.cadenceworks.tech	Private app hosting
dev.puterN.cadenceworks.tech	Alt private app hosting
s3.puterN.cadenceworks.tech	Browser-facing S3 (presigned URLs)

Verification

curl -sI http://127.0.0.1:410N/
# or via Hermes
ssh aux 'bash scripts/puter-verify.sh'

Related

• Caddy configuration — TLS and reverse proxy blocks
• DNS records — external hostname mapping
• Recover HeyPuter — incident response
• Back up with restic — data paths to back up
• HeyPuter upstream self-hosting guide