Install with an AI agent

You are the System admin of the new server. An AI coding agent (Claude Code, Codex, or similar) can do the typing: it reads the install guide, runs firstboot.sh on your box, and reports whether verify-stack.sh passed. You answer four questions and keep the decisions.

This is the same install as Install, driven by an agent.

What you need

• A Linux box with Docker (Compose v2) and Node.js, and the TeamHUD server bundle unpacked on it (see Install for how the bundle is handed over).
• SSH access to that box for the agent, or run the agent on the box itself.
• To go live: a domain with a DNS A record pointing at the box, and ports 80 and 443 open.
• A coding agent that can run shell commands and fetch a web page.

The prompt

Paste this into your agent. Replace the two bracketed parts.

Install a self-hosted TeamHUD server on [user@host, or "this machine"].

1. Fetch https://teamhud.app/docs/llms-install.txt and follow it step by step.
   The TeamHUD bundle is at [path to the unpacked bundle, deploy/teamhud].
2. Run ./firstboot.sh. Ask me for anything it needs that I have not given you:
   the public hostname, the address clients reach the box on, the addresses
   allowed to open /admin, whether sign-up is open or closed, and whether people
   sign in with Slack or Microsoft.
   Do not invent answers.
3. Stop and ask me before anything destructive: deleting files or volumes,
   `docker compose down -v`, overwriting .env or any secret, changing the
   firewall, or re-running over an existing install.
4. When it finishes, run ./verify-stack.sh and report each check as pass or
   fail, with the exact output of any failure. Do not say it works unless
   verify-stack.sh passed.
5. Do not print secrets back to me except the one-time setup link.

Tip

Using Claude Code? Run it inside the bundle directory. It also picks up AGENTS.md there, which lists the safe and unsafe commands.

What the agent will ask you

Question	What to answer
Public hostname	Your domain, for example teamhud.example.com, with DNS already pointing at the box. Leave it blank to get an automatic <ip>.sslip.io name.
Addresses allowed to open /admin	Your office or VPN IP. Locks the System admin pages to it.
Invite-only sign-up: people join with an invitation sent to their email?	true (the default) means you invite every account; false lets anyone with the address create an account.
Sign in with Slack? Sign in with Microsoft (Teams)?	false unless you have the app registration ready; the agent then asks for its client ID and secret.
Install the game server?	true by default; team mini-games.

It may also ask for the address clients reach the box on, which is usually the box’s public IP.

Check that it worked

1. The agent reports verify-stack.sh passed, all checks. A green docker compose ps is not enough: see Troubleshooting.
2. Open the setup link the agent gives you, https://<your-host>/setup?token=…, and create the first account. It becomes a System admin.
3. In the desktop app, choose Use a different TeamHUD server on the sign-in screen and enter https://<your-host>.

If a check failed, hand the output back to the agent, or see Going live on a domain and Troubleshooting.