AT Protocol Development Environment#

A Nix-based development environment for running AT Protocol services (PDS, PLC, Caddy proxy, and MailHog).

Prerequisites#

1. Install mkcert (required for SSL certificate generation):

   • On macOS: brew install mkcert
   • On Linux: See mkcert installation guide
   • After installation, run: mkcert -install

2. Add hosts file entries:

   127.0.0.1 pds.example.org
   127.0.0.1 plc.example.org
   127.0.0.1 relay.example.org
   

3. Generate SSL certificates before first use:

   nix run .#generate-certs
   

Quick Start#

1. Enter the development environment:

   nix develop
   

2. Start all services in tmux:

   nix run .#all
   

   This will start all services in a single-column tmux pane layout:

   • Pane 0: PLC server
   • Pane 1: PDS server
   • Pane 2: Caddy proxy
   • Pane 3: AT Protocol Relay

3. Add PDS host to the relay:

   goat relay --relay-host=https://relay.example.org:8445 admin --admin-password=password host add "https://pds.example.org:8443"
   

4. Create an invite code:

   scripts/create-invite.sh
   

5. Create a user account:

   goat account create \
     --pds-host=https://pds.example.org:8443 \
     --password=password \
     --email=hello@example.org \
     --invite-code=pds-example-org:8443-xyldq-yrhxc \
     --handle=edouard.pds.example.org
   

6. Verify the DID is registered:

   goat plc --plc-host=https://plc.example.org data <your-did>
   

7. Login to your account:

   goat account login \
     --username=edouard.pds.example.org \
     --app-password=password \
     --pds-host=https://pds.example.org:8443
   

8. Create your first post:

   goat bsky post "hello world!"
   

Services#

• Bluesky PDS: https://pds.example.org:8443
• DID PLC: https://plc.example.org:8444
• AT Protocol Relay: https://relay.example.org:8445
• MailHog: http://localhost:8025

Monitoring#

To monitor the AT Protocol relay firehose:

goat firehose --relay-host wss://relay.example.org:8445

This will show real-time events from the relay. You can run this in a separate terminal or tmux pane.

Management Commands#

• tmux attach -t atproto - Attach to the services session
• tmux kill-session -t atproto - Stop all services
• nix run .#mailhog - Start MailHog (run separately if needed)
• nix run .#generate-certs - Generate SSL certificates

⚠️ Security Warning#

This environment uses a modified AT Protocol relay with SSRF protection disabled.

• The relay is built from a forked repository (edouardparis/indigo) with SSRF (Server-Side Request Forgery) protections disabled
• Custom ports are allowed without restrictions
• This configuration is ONLY safe for local development environments
• DO NOT use this relay configuration against external hosts or in production
• DO NOT expose this relay to the internet

This setup is designed for controlled local testing where you need flexibility in network access that would normally be restricted for security reasons.