AT Protocol Development Environment#

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

⚠️ 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.

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