Agentry Gateway Documentation

# Build the image
git clone https://github.com/amtp-protocol/agentry.git && cd agentry
make docker-build

# Create an admin key and start the gateway
mkdir -p keys && openssl rand -hex 32 > keys/admin.keys
export ADMIN_KEY=$(cat keys/admin.keys)
docker run -d -p 8443:8443 \
  -e AMTP_DOMAIN=localhost \
  -e AMTP_TLS_ENABLED=false \
  -e AMTP_ADMIN_KEY_FILE=/app/keys/admin.keys \
  -v $(pwd)/keys:/app/keys:ro \
  agentry:latest

curl http://localhost:8443/health

for name in alice bob; do
  curl -X POST http://localhost:8443/v1/admin/agents \
    -H "Content-Type: application/json" \
    -H "X-Admin-Key: $ADMIN_KEY" \
    -d "{\"address\": \"$name\", \"delivery_mode\": \"pull\"}"
done

# Save the keys from the responses
export ALICE_KEY=...
export BOB_KEY=...

curl -X POST http://localhost:8443/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ALICE_KEY" \
  -d '{
    "sender": "alice@localhost",
    "recipients": ["bob@localhost"],
    "subject": "Hello",
    "payload": {"text": "Hello from Alice"}
  }'

curl -H "Authorization: Bearer $BOB_KEY" \
  http://localhost:8443/v1/inbox/bob@localhost

curl -X DELETE -H "Authorization: Bearer $BOB_KEY" \
  http://localhost:8443/v1/inbox/bob@localhost/<message_id>

POST /v1/messages
Authorization: Bearer <sender agent api_key>

{
  "sender": "orders@company.com",
  "recipients": ["fulfillment@partner.com"],
  "subject": "New order",
  "schema": "agntcy:commerce.order.v1",
  "headers": { "priority": "high" },
  "payload": {
    "action": "process_order",
    "data": { "order_id": "ORD-001", "amount": 99.99, "currency": "USD" }
  }
}

# docker-compose.yml
services:
  agentry:
    image: agentry:latest   # built with make docker-build
    ports:
      - "8443:8443"
    environment:
      - AMTP_DOMAIN=yourcompany.com
      - AMTP_TLS_CERT_FILE=/app/certs/tls.crt
      - AMTP_TLS_KEY_FILE=/app/certs/tls.key
      - AMTP_ADMIN_KEY_FILE=/app/keys/admin.keys
      - AMTP_SIGNATURE_PRIVATE_KEY_FILE=/app/keys/signing.pem
      - AMTP_STORAGE_TYPE=database
      - AMTP_STORAGE_DATABASE_DRIVER=pgx
      - AMTP_STORAGE_DATABASE_CONNECTION_STRING=host=postgres port=5432 user=agentry password=change-me dbname=agentry
    volumes:
      - ./certs:/app/certs:ro
      - ./keys:/app/keys:ro
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: agentry
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: agentry
    volumes:
      - ./deployment/db:/docker-entrypoint-initdb.d:ro
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U agentry"]
      interval: 10s
      retries: 5

volumes:
  postgres_data:

# Where other gateways deliver mail for your domain
_amtp.yourcompany.com.        IN TXT "v=amtp1;gateway=https://amtp.yourcompany.com:443"

# Public key that verifies your domain signatures (selector k1)
k1._amtpkey.yourcompany.com.  IN TXT "v=amtpkey1;alg=ES256;p=<base64-public-key>"