Your own server

pigeon is small. So are the other tools worth self-hosting. One cheap VPS runs several of them — you do about ten minutes of work by hand, then you prompt an agent for the rest.

One box. $5 a month.

This page as a file: docs/your-server.md.

What you are buying

Any provider with a small Linux instance works. Around $5 / €5 a month buys roughly 1–4 GB of RAM, a shared vCPU and 20–50 GB of disk. Prices and tiers move constantly — treat the names below as where to look, not as a quote.

Widely used, global regions

Europe

Asia-Pacific, and elsewhere

Pick the region deliberately. Two things depend on it and neither is speed: the jurisdiction your mail tokens sit in, and — if you are in the EU or serving EU users — whether you have just made your own life harder under GDPR. An EU-resident host is the simpler answer there. Otherwise choose the city closest to you, not the cheapest one.

1 GB is comfortable for pigeon plus a couple of other small Python services behind nginx. If you plan to add a database and three or four more tools, start at 2–4 GB — it is a few more dollars, and resizing later means downtime. ARM instances are cheaper and work fine here; just check anything you install has an arm64 build.

The part you do by hand

Everything here is done once, as root, before any agent is involved. It exists so the agent has a safe account to work in and a name to get a certificate for.

1. Create the instance

   Ubuntu LTS. Paste your SSH public key into the create form — doing it now means you never enable password login at all.

2. Point a DNS name at it

   An A record for the host you want, e.g. domain.com → the instance IP. Do this early; certificates need the name to resolve.

3. Update, and make yourself a user

   Log in as root once and run the update, then create a normal account with sudo and copy your key to it. From then on you log in as that user, not root.

   apt update && apt full-upgrade -y
   adduser you
   usermod -aG sudo you
   rsync --archive --chown=you:you ~/.ssh /home/you/

4. Install your agent, and stop typing

   Install whichever coding agent you use, log in as your user, and start it in a working directory. That is the end of the manual part.

Worth knowing before you start

• The agent has your sudo Give it a user account, not a root login
• $5 is the box, not the backups Ask it to set up an off-box backup too
• This host will hold mail tokens Its security is your mailbox's security
• Cheap instances are shared Fine for tools; not for anything latency-critical

Then you prompt for the rest

This is the actual technique: you are not learning to administer a server, you are learning to direct one. Work in small steps, ask for an explanation before a change, and ask for evidence after it.

Give the agent sudo through your user — not a root login. An agent with sudo can do anything you can do, which is the point and also the risk. Small steps keep it reviewable.

1 · Look before touching

You are on a fresh Ubuntu server that will be on the public
internet. Change nothing yet. Tell me: what is installed, what
is listening on a port, what the firewall state is, and what
you would change before this box is exposed. List it as
findings, worst first.

2 · Basic hardening

Do the standard hardening for a small public server:
unattended security upgrades, a firewall allowing only SSH,
HTTP and HTTPS, SSH key-only authentication, and fail2ban.
Explain each change before you make it, and after each one
show me the command that proves it took effect.

3 · A name and a certificate

Install nginx and certbot. Set up domain.com with a
Let's Encrypt certificate. Then prove renewal actually works
with a dry run — do not just tell me it is configured.

That last sentence matters more than it looks. A certificate that installs cleanly and silently fails to renew is a site that breaks in ninety days.

4 · Install pigeon

Install pigeon-mcp from https://github.com/iXanadu/pigeon-mcp
on this server, following the repo's deploy documentation.
Run it as its own service user, never as root or as me. Bind
it to loopback and put nginx in front with the certificate you
just set up. Read deploy/DEPLOYING.md first and tell me what
it requires before you start.

How to talk to it

• Ask for proof, not a report. “Show me the command that proves it” beats “is it working?” — an agent that says done is describing its intent, not the machine.
• One thing at a time. A prompt that installs and configures and hardens in one pass is one you cannot review.
• Make it explain first. If the explanation is wrong, you have caught it before it ran.
• Keep the secrets out of the chat. Tokens and keys belong in files on the server. Tell it to write them there and show you the permissions, not the contents.