As of 2026-01-17, this works but things change rapidly.

High Level Bullet Points

OAuth Client Config

/* OAUTH client config */
 const client = new BrowserOAuthClient({
    clientMetadata: getConfig(import.meta.env.PROD),
    // https://www.npmjs.com/package/@atproto/oauth-client-browser
    handleResolver: "http://127.0.0.1:2583",
    plcDirectoryUrl: "http://127.0.0.1:2582",
    allowHttp: true,
  });

Podman Compose for local atproto dev-env

# Podman Compose configuration for atproto PDS development
# Includes PostgreSQL and Redis services

version: '3.8'

services:
  postgres:
    image: postgres:latest
    container_name: atproto_pds_postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: postgres
      PGDATA: /var/lib/postgresql/data/pgdata
    ports:
      - '5433:5432'
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      timeout: 5s
      retries: 5
    volumes:
      - postgres_data:/var/lib/postgresql
    restart: unless-stopped
    networks:
      - atproto_network

  redis:
    image: redis:latest
    container_name: atproto_pds_redis
    ports:
      - '6379:6379'
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 5s
      retries: 5
    volumes:
      - redis_data:/data
    restart: unless-stopped
    networks:
      - atproto_network
volumes:
  postgres_data:
    name: atproto_postgres_data
  redis_data:
    name: atproto_redis_data

networks:
  atproto_network:
    name: atproto_network
    driver: bridge

Test User curl command

curl -X POST http://localhost:2583/xrpc/com.atproto.server.createAccount \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "yolo.test",
    "email": "yolo@example.com",
    "password": "password123"
  }'

Why LocalStacks are Important?

Being able to run software locally and debug it is vital for a healthy atproto atmosphere and to stop lock in. Developers have been wrestling this back from cloud providers. We should be vigilant about it with atproto.

Likewise, testing data can pollute the main network. PDS.rip helps with this, but it could ultimately disappear any day.