setup-vps

Turn the server the user reached with ssh hermes into their own agent that runs 24/7: it gets their GitHub and Cloudflare access, runs Hermes on their Claude subscription, answers them on Telegram or Discord, and shows its dashboard at https://hermes.<domain>, where every page the server puts online sits behind one gate: a sign-in page open to every address where each person types their email and the 6-digit code Lumail sends them (no password to leave lying around, one access per person, admin or member), locked after repeated failures, where the user can save their home or office IP to skip it next time. The first argument is the domain (ask if missing and they have several in cf zones list), the second the alias (default hermes; use it everywhere below). With discord as the first argument, only connect Hermes to Discord on a server where it already runs: check ssh -o BatchMode=yes hermes true, follow references/discord.md from its step 1, and stop there. Do every step yourself and only ask for what needs a human (signing in, creating a bot, reading a code in their inbox). Talk to the user in their language, short messages, no jargon (never say "token", "tunnel", "reverse proxy" or "systemd" to them; say "access", "the secure link" and "the service"). Write every rule you add (the style block, the ## VPS blocks) in English, whatever language you talk in.

If you got this skill from a link instead of a local folder, install nothing else from the repo: download a file it links only when a step needs it, with curl -fsSL https://raw.githubusercontent.com/Melvynx/ai-maxxing-skills/main/skills/setup-vps/<path> -o <scratch>/<file> (for example scripts/expose.sh), and read another skill it names only when you reach it, from https://raw.githubusercontent.com/Melvynx/ai-maxxing-skills/main/skills/<skill-name>/SKILL.md.

Never print a token, a key or a password from the Mac or the server, except the one gate password of the fallback in step 12, which the user needs to save. Tokens travel through pipes from one machine to the other, and anything the user must type (a bot token, an API key, their own password) they type in their own Terminal, never in the chat. Run every remote command as ssh hermes '<command>' < /dev/null; when the login user is not root, prefix install and expose with sudo, never hermes-setup (it asks for sudo itself). Never open a port on the server's firewall and never publish a page any other way than expose add.

1. Check what is ready: ssh -o BatchMode=yes hermes true (otherwise run the connect-vps skill), gh auth status (otherwise setup-github), cf auth whoami says authenticated (otherwise setup-cloudflare), and jq --version (otherwise brew install jq). If CLOUDFLARE_ACCOUNT_ID is empty and cf accounts list shows several accounts, ask which one and export it.
2. Put the server scripts in place: scp scripts/hermes.sh scripts/expose.sh scripts/gate.py scripts/geist.woff2 scripts/discord.sh hermes:/tmp/, then ssh hermes 'install -m 755 /tmp/hermes.sh /usr/local/bin/hermes-setup && install -m 755 /tmp/expose.sh /usr/local/bin/expose && install -D -m 755 /tmp/gate.py /usr/local/lib/vps-gate/gate.py && install -m 644 /tmp/geist.woff2 /usr/local/lib/vps-gate/ && install -m 755 /tmp/discord.sh /usr/local/bin/hermes-discord'. Then the skills that teach the agent its tools: ssh hermes 'mkdir -p /tmp/vps-skills' and scp -r server-skills/server-tools server-skills/github-cli server-skills/ai-maxxing-skills ../cloudflare hermes:/tmp/vps-skills/ (from a link, download each of the four SKILL.md into <scratch>/vps-skills/<name>/ first, the Cloudflare one from skills/cloudflare/SKILL.md, then scp -r <scratch>/vps-skills/* hermes:/tmp/vps-skills/). hermes-setup, expose and hermes-discord print their commands when run without arguments.
3. Give the server the user's GitHub with scripts/import-keys.sh github hermes. It installs gh there, signs it in with the Mac's access through a pipe, makes git push work, and copies their git name and email.
4. Give it Cloudflare with import-keys.sh cloudflare hermes. It creates an access named vps-hermes that only works from the server's own address (tunnels, DNS, Workers, Pages, R2, KV, D1, firewall, cache) and saves it in ~/.config/cloudflare/env on the server, loaded by every shell. Rerunning it does nothing while that access works; a new one replaces the old.
5. Install Claude Code and Hermes with ssh hermes 'hermes-setup install', in the background (it takes a few minutes); it skips what is already there and prints both versions.
6. Sign Claude Code in on the server. Tell the user to run ssh -t hermes claude in their own Terminal, sign in with their Claude account, open the link it shows, approve, paste the code back, then type /exit. Check with ssh hermes 'hermes-setup claude': exit code 5 means not signed in yet; on success it prints default_model.
7. Choose the model. The recommended one is that default_model (Claude Code's default, claude-opus-5-5 today) with effort medium; if the user asked for another model or effort, use theirs. Run ssh hermes 'hermes-setup model <model> medium'; it ends with Hermes answering "OK". On exit code 6, follow the model part of references/hermes.md (most often the subscription's extra usage). Then copy the Cloudflare access into Hermes with import-keys.sh hermes-env hermes.
8. Set up the chat. Ask Telegram or Discord (Telegram is the quickest on a phone, Discord the most hands-off and the best for a team). Telegram: follow its part of references/hermes.md; the user creates the bot and types its token in hermes gateway setup in their own Terminal, you run ssh hermes 'hermes-setup gateway'. Discord: follow references/discord.md from its step 2; you create the bot in Chrome AI and hermes-discord sets up the server, its private channel and who may talk to the agent. The step is done when the bot answers their "hello".
9. Give Hermes the user's working style, the ## Output style block that setup-brain wrote in the Mac's global rules: awk '/^## Output style[[:space:]]*$/{f=1;print;next} f&&/^## /{f=0} f' ~/.claude/CLAUDE.md | ssh hermes 'hermes-setup style'. It answers style ok, ssh hermes 'hermes-setup check' then shows style=set, and it puts the block in Hermes's SOUL.md and in Claude Code's rules on the server, replacing an older one. When the Mac has no such block, ask questions 2, 3, 4 and 9 of the setup-brain interview, build the block with its references/output-style.md (next to the setup-brain skill, or https://raw.githubusercontent.com/Melvynx/ai-maxxing-skills/main/skills/brain/setup-brain/references/output-style.md), add it to ~/.claude/CLAUDE.md too, then run the same command. Then let Hermes work on its own: ssh hermes 'hermes-setup autonomy'. It stops asking "may I run this?" before each action (it can also edit its own instruction files), shows a short line in the chat for each tool it uses, and restarts the chat. Tell the user in one line that Hermes now acts without asking, so it only follows their own instructions, and that /approvals in the chat brings the questions back.
10. Teach it its tools: ssh hermes 'hermes-setup skills <domain> /tmp/vps-skills'. It installs Cloudflare's cf command on the server and puts the server-tools, github-cli, cloudflare and ai-maxxing-skills skills in ~/.agents/skills, the one folder for every skill on the server: Hermes reads it and ~/.claude/skills links to it, so Claude Code on the server sees the same skills. A skill the user already has under the same name is kept. Then give it the default pack of the package: ssh hermes 'hermes-setup add base' (the list in hermes-pack: the server's tool skills, create-dashboard, connect-tool, create-internal-app; hermes-setup catalog marks them base). More come with the install-skills skill, or by asking Hermes "install the create-landing skill" (ai-maxxing-skills teaches it hermes-setup catalog and add).
11. Build the gate with ssh hermes 'expose install': it installs Cloudflare's connector, Caddy and the sign-in page (scripts/gate.py, the vps-gate service, in the Hermes look with its Geist font), creates the secure link (named after the server) and starts all three, without touching anything else that already runs on the server. Rerun it after updating gate.py or expose.sh; it keeps the users, the Lumail key, the login and the saved IPs.
12. Turn on the email sign-in, the default. The owner is the first admin: their email (ask, or take git config --global user.email), then ssh hermes 'expose user add <email> admin'. Codes leave from Lumail with the user's own domain:
    • Lumail must work on the Mac: npx -y lumail@latest auth test, otherwise run the setup-lumail skill first.
    • The domain must be able to send: npx -y lumail@latest --json domain setup <domain> lists data.status and data.dnsRecords. Unless the status is VERIFIED, add each record in Cloudflare yourself (cf dns records create, never proxied), then run npx -y lumail@latest --json domain verify <domain> every 30 seconds until VERIFIED (up to 10 minutes; DNS can take a while to spread).
    • Give the gate its own key, through a pipe, never printed: npx -y lumail@latest --json tokens create --name "Sign-in <alias>" --permissions emails --no-reuse | jq -r '.token // .data.token' | ssh hermes 'expose mail "<Alias> <login@<domain>>"' (<Alias> is the alias with a capital letter, the name people see in their inbox). It first sends a test email to the owner and only turns codes on if Lumail accepted it: tell the user to check their inbox (spam too). Exit code 5 prints Lumail's reason (often the domain not verified yet); fix it and rerun.
    • Fallback, only if the user has no Lumail account and does not want one: ssh hermes 'expose login <email>'. It prints a generated password once: give it to the user with their email, tell them to save both in their password manager right now, and never write it anywhere. To choose it, they run ssh -t hermes 'expose login <email> --stdin' in their own Terminal (12 characters or more). Email codes can be turned on later with the commands above.
13. Explain the gate in 4 short lines. Every address reaches the sign-in page: they type their email, get a 6-digit code by email (valid 10 minutes), and the session lasts 7 days. Other people get access with "add <email> to the dashboard" (Hermes runs expose user add <email> member --invite, which emails them the links): a member opens the pages made for the team, an admin opens everything, the Hermes dashboard included; expose user remove <email> signs someone out at once. Right after an admin signs in from home or the office, the page offers "Sauvegarder cette IP": that network then skips the sign-in, but only after they tick that it is their own network and not a public Wi-Fi (cafe, hotel, coworking, airport); a 4G network, a VPN or a server address is never offered and refused if forced. 5 wrong codes lock that address for 15 minutes (then 30, 60, up to 24 hours), and 30 failures in 15 minutes lock the sign-in for every address that is not saved; ssh hermes 'expose unlock' clears the locks. Never save an IP for them yourself; expose allow <ip> is only for an address they name and confirm is their own private network.
14. Put the dashboard online: ssh hermes 'hermes-setup dashboard', then ssh hermes 'expose add hermes.<domain> 9119 --as-local --admins' (the Hermes dashboard can run anything on the server, so only admins open it). Exit code 4 means hermes.<domain> already points somewhere else: ask before picking another name such as agent.<domain>. Then ssh hermes 'expose status' must list site=hermes.<domain> admins-only, sign_in=code (or sign_in=password with the fallback) and no line starting with UNPROTECTED.
15. Prove it from the Mac, after a minute for the address to spread: curl -s -o /dev/null -w '%{http_code} %{redirect_url}' https://hermes.<domain> answers 302 to /.gate/login. Then ask the user to open https://hermes.<domain> in their browser, type their email, then the code they receive (or the password with the fallback), choose whether to save this IP, and say what they see; the Hermes dashboard means done. ssh hermes 'expose status' then shows their saved IP if they chose it.
16. Tell every agent, in the ## VPS block that connect-vps wrote (brain AGENTS.md, ~/.claude/rules/vps.md, ~/.codex/AGENTS.md if Codex is installed), keeping every existing line: Hermes runs on the server and answers on Telegram or Discord, the dashboard is https://hermes.<domain>, GitHub and Cloudflare work from the server, the server's skills live in ~/.agents/skills (read by Hermes, linked in ~/.claude/skills), and to put any page online always run ssh hermes 'expose add <name>.<domain> <port>', never a tunnel route, an open port or a public bind. People sign in with their email and a code; expose user add <email> member|admin --invite gives someone access, expose user remove <email> takes it away, and --admins on expose add keeps a page for admins. New places are saved by the user from the sign-in page; expose unlock clears a lock after too many wrong codes.

End with a short check list, a check or a cross on each line: GitHub on the server (account name), Cloudflare on the server, Claude Code signed in, Hermes answers (model and effort), chat works (Telegram or Discord), Hermes has the user's output style, Hermes acts without asking and shows its tools, tool skills installed (server-tools, github-cli, cloudflare, ai-maxxing-skills), default pack installed (hermes-setup catalog shows every base line installed or own), gate built (sign-in by email code, test email received, owner admin, saved IPs, brute-force lock on), dashboard online at https://hermes.<domain>, no unprotected page, agents told. Then tell the user in 3 lines: send a message to their bot to give the agent a task, open https://hermes.<domain> to watch it work, ask "put my site online on the server" when they want a new page behind the same gate, "add <email> to the dashboard" to let someone in, and ask "which skills can you install?" to give it more.