Tutorial: Getting started with the HeyPuter fleet on auxserver

Goal: Understand one HeyPuter instance end-to-end: open the desktop, verify containers, and perform the one restart that almost every upgrade needs.

Time: ~30 minutes
Level: Intermediate (Docker Compose)

Prerequisites

• Completed First day on aux or equivalent SSH access
• Browser
• Optional: read Why the container platform looks like this

Background (short)

Four independent Puter stacks live under ~/puter/instance{1..4}. Browser traffic path:

Browser → Caddy :443 → 127.0.0.1:410N → instance nginx :80 → puter :4100

Use the apex URL https://puterN.cadenceworks.tech for the desktop OS. site.puterN… is user static hosting, not the OS.

1. Pick instance 1 and inspect compose

cd ~/puter/instance1
ls
docker compose ps

Expect services such as puter, nginx, mariadb, valkey, dynamo, s3 (names may vary slightly by compose revision). Ollama appears only when the ai profile is enabled (instances 1–2).

2. Local health check

curl -sI http://127.0.0.1:4101/ | head -10

A successful response from nginx on the host loopback means Caddy can proxy to this instance.

3. Open the desktop

In a browser:

https://puter1.cadenceworks.tech

You should get the Puter login/desktop shell over valid HTTPS (certificate from Caddy / Let's Encrypt).

4. Practice the post-recreate nginx restart

After any recreate of the puter container, nginx can cache a stale upstream IP and return 502. Practice the safe fix without changing images:

cd ~/puter/instance1
docker compose restart nginx
curl -sI http://127.0.0.1:4101/ | head -5

5. Read the instance matrix (do not memorize)

Open HeyPuter reference and note:

• Ports 4101–4104
• Image pin ghcr.io/heyputer/puter:26.05.2 (avoid blind :main)
• Data path ~/puter/instanceN/puter/data/
• Config secrets stay in .env / config.json — never paste into docs

6. Optional fleet verify script

If present on the operator machine or via Hermes:

bash ~/puter/scripts/puter-verify.sh
# or from Hermes VPS patterns documented in operator skills

Success criteria

• [ ] docker compose ps healthy for instance 1
• [ ] Loopback curl to :4101 succeeds
• [ ] Apex HTTPS desktop loads
• [ ] You can restart nginx and re-check without fear
• [ ] You know where the pin/tag and data paths are documented

Next steps

• Incident recovery: How to recover a HeyPuter instance
• Upgrade procedure: How to update Docker containers
• Design rationale: Container platform explanation