Environment variables
Every variable pds reads, as the specification’s pages give them, page by page. This page is made from those pages’ tables; each page says the rest of what its variables do.
| Variable | Description | Default |
|---|---|---|
PDS_PORT | the port to listen on | required |
PDS_BIND_ADDRESS | the address to listen on: an IPv4 or IPv6 address, as 0.0.0.0 for every IPv4 address of the machine, or :: for every address an IPv6 socket is given, which on Linux and macOS is every IPv4 address too | 127.0.0.1 |
PDS_DATA_DIR | a directory for its data: empty the first time, and the server’s own after | required |
| Variable | Description |
|---|---|
PDS_HOSTNAME | the server’s hostname; the server’s DID is did:web:<hostname> |
PDS_PUBLIC_URL | the URL its DID documents name as the account’s PDS |
PDS_HANDLE_DOMAINS | the domains handles may end in, comma-separated, each with its leading dot, such as .test |
PDS_PLC_URL | the PLC directory it registers DIDs with |
PDS_PLC_ROTATION_KEY_HEX | its secp256k1 PLC rotation key, 32 bytes as hex |
PDS_RECOVERY_DID_KEY | optional: a did:key listed before the server’s own as a rotation key of every DID it creates |
| Variable | Description | Default |
|---|---|---|
PDS_BLOBSTORE_S3_BUCKET | the bucket; unset, blobs are kept in PDS_DATA_DIR | unset |
PDS_BLOBSTORE_S3_REGION | the region requests to the store are signed for | us-east-1 |
PDS_BLOBSTORE_S3_ENDPOINT | the store’s base URL, http or https, with no query or fragment, as https://<account>.r2.cloudflarestorage.com; unset, Amazon’s, https://s3.<region>.amazonaws.com | unset |
PDS_BLOBSTORE_S3_FORCE_PATH_STYLE | true: the bucket is the first segment of each request’s path, <endpoint>/<bucket>/<key>; false: the first label of its host, <bucket>.<endpoint's host>/<key> | false |
PDS_BLOBSTORE_S3_ACCESS_KEY_ID, PDS_BLOBSTORE_S3_SECRET_ACCESS_KEY | the credentials requests are signed with; both unset, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from the environment, with AWS_SESSION_TOKEN if it is set | unset |
PDS_BLOBSTORE_S3_UPLOAD_TIMEOUT_MS | how long storing one upload may take, in milliseconds | 20000 |
PDS_BLOBSTORE_S3_REQUEST_TIMEOUT_MS | how long any other request to the store may take, in milliseconds | 10000 |
Commands: every method as an MCP tool and a CLI command
Section titled “Commands: every method as an MCP tool and a CLI command”| Variable | Description |
|---|---|
PDS_URL | the server’s base URL |
PDS_TOKEN | a bearer token to send, if set |
PDS_ADMIN_PASSWORD | with no PDS_TOKEN, the admin’s password, sent as Basic with the user admin |
| Variable | Description | Default |
|---|---|---|
PDS_SYNC | how waiting writes are made durable: together, every account’s by one sync; or each, each account’s by a sync of its own, which only the writes waiting on that account share | together |
| Variable | Description |
|---|---|
PDS_EMAIL_SMTP_URL | the SMTP server to send through: smtp://[user:password@]host[:port], upgraded with STARTTLS when the server offers it, or smtps://... for TLS from the start; user and password percent-encoded |
PDS_EMAIL_FROM | the address each email is from |
| Variable | Description |
|---|---|
PDS_DEV_MAIL_DIR | optional: a directory each email is also written to, for tests |
| Variable | Description |
|---|---|
PDS_CRAWLERS | optional: the base URLs of the crawlers (relays) to notify, comma-separated, such as http://127.0.0.1:2470 |
| Variable | Description | Default |
|---|---|---|
PDS_HANDLE_DNS_SERVER | the DNS server asked for a handle’s _atproto TXT records: an IPv4 or IPv6 address, with an optional port, as 127.0.0.1:5353 or [::1]:5353 | unset: the system’s resolver |
PDS_HANDLE_FETCH | for development and testing only: a base URL, http:// or https://, a host, an optional port and path, with no trailing /, from which every handle’s /.well-known/atproto-did is fetched instead (below) | unset |
| Variable | Description | Default |
|---|---|---|
PDS_INVITE_REQUIRED | true or false: whether createAccount needs an invite code | false |
PDS_ADMIN_PASSWORD | the password of the admin methods’ Basic auth; unset or empty, no request is the admin | unset |
PDS_RATE_LIMITS_ENABLED | true or false: whether the rate limits below apply | true |
PDS_BLOB_QUOTA_BYTES | the bytes of blobs an account may hold | 1073741824 (1 GiB) |
PDS_BLOB_TTL_SECS | how long an upload no record references is held | 3600 |
PDS_BLOB_UPLOAD_LIMIT | the bytes of a blob uploadBlob takes (Blobs), and of a space repo’s archive com.atproto.space.importRepo takes (Spaces: a repo whole, its blobs, and migration), as the reference names it; describeServer answers it as blobUploadLimit | 5242880 (5 MiB, the reference’s) |
PDS_MIN_FREE_BYTES | the free space below which writes are refused | 268435456 (256 MiB) |
PDS_MAX_REPO_IMPORT_SIZE | the bytes of the CAR file com.atproto.repo.importRepo takes (Moving an account between servers), as the reference names it. The default is what the reference’s own installer gives it (the upload limit it sets, which bounds its imports too); the reference’s bare default, 5 MiB, would refuse most accounts’ repositories | 314572800 (300 MiB) |
PDS_DID_CACHE_SECS | how long a DID document is held before it is fetched again: an account’s, from the directory or, for a did:web, its host (Moving an account between servers), a service token’s issuer’s (Moving an account between servers, createAccount), and the key of a spaces token’s issuer, read again after its answer past this (Spaces: credentials, “Issuers’ keys”) | 3600 |
PDS_DID_CACHE_MAX_SECS | how long the key of a spaces token’s issuer is used at all: past PDS_DID_CACHE_SECS, a call is answered with it while it is read again; past this, it is read again first (Spaces: credentials, “Issuers’ keys”) | 86400 (a day) |
PDS_TRUSTED_PROXIES | the proxies before the server, whose X-Forwarded-For it reads: addresses and CIDR ranges, IPv4 or IPv6, separated by commas (127.0.0.1,10.0.0.0/8,::1); unset or empty, none | unset |
OAuth: web, native and confidential clients
Section titled “OAuth: web, native and confidential clients”| Variable | Description |
|---|---|
PDS_OAUTH_CLIENT_FETCH | for development and testing only: the origins whose client documents and JWKS are fetched from another base URL, as below |
| Variable | Description |
|---|---|
PDS_LEXICON_AUTHORITY_DID | optional: a DID that is every NSID’s authority, in place of DNS (above). One that is not a DID makes pds serve exit 1, with why on standard error |
| Variable | Description | Default |
|---|---|---|
PDS_LOG_LEVEL | the least level of log line written: debug, info, warn or error; or off, for none | info |
PDS_LOG_DIR | a directory the log is kept in too, for the admin to read back (“Kept”, below); made if missing; unset, the log is kept nowhere but standard output | unset |
PDS_LOG_KEEP_BYTES | the most bytes the files in PDS_LOG_DIR take together; at least 65536 | 67108864 (64 MiB) |
PDS_METRICS_PORT | the port /metrics is served on, on 127.0.0.1; unset, metrics are not served | unset |
OTEL_EXPORTER_OTLP_ENDPOINT | the base URL of the OTLP receiver traces go to: they are posted to it with v1/traces appended, after a / if it does not end in one | unset |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | the URL traces are posted to, as it is; before OTEL_EXPORTER_OTLP_ENDPOINT | unset |
OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_TRACES_PROTOCOL | http/protobuf, the only protocol the server speaks | http/protobuf |
OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS | headers sent with each export, key=value pairs joined by ,, each value percent-decoded; the second’s pairs win | none |
OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_TRACES_COMPRESSION | gzip or none | none |
OTEL_SERVICE_NAME | the service.name of the server’s spans | unknown_service:pds |
OTEL_SDK_DISABLED | true turns traces off, whatever else is set | false |
OTEL_BSP_SCHEDULE_DELAY | milliseconds between exports | 5000 |
OTEL_BSP_MAX_QUEUE_SIZE | spans held for export at most; past it, new spans are dropped | 2048 |
OTEL_BSP_MAX_EXPORT_BATCH_SIZE | spans in one export at most | 512 |
OTEL_BSP_EXPORT_TIMEOUT | milliseconds an export may take, retries and all, before its spans are dropped | 30000 |
| Variable | Description |
|---|---|
PDS_BSKY_APP_VIEW_URL | the default AppView’s URL, such as https://api.bsky.app |
PDS_BSKY_APP_VIEW_DID | its DID, such as did:web:api.bsky.app |
PDS_BSKY_APP_VIEW_CDN_URL_PATTERN | optional: the URL of an image on the AppView’s CDN, with three %s, as https://cdn.bsky.app/img/%s/plain/%s/%s@jpeg |
PDS_DISABLE_SSRF_PROTECTION | optional: true or 1 turns protection off, false, 0, empty or unset leaves it on; for development and testing only, a server open to the internet must not set it. Any other value makes pds serve exit 1, with why on standard error (the reference takes it as unset) |
Spaces: write notifications, the writer set and syncers
Section titled “Spaces: write notifications, the writer set and syncers”| Variable | Description |
|---|---|
PDS_DISABLE_SSRF_PROTECTION | as Proxying, service auth and preferences defines it, for every request the server sends to a URL others name: true or 1 turn protection off; false, 0, empty or unset leave it on; any other value makes pds serve exit 1 |
The store: what is kept, the backfill window, and the bounds
Section titled “The store: what is kept, the backfill window, and the bounds”| Variable | Description | Default |
|---|---|---|
PDS_REPO_BACKFILL_LIMIT_MS | the backfill window W: how far back, in milliseconds, subscribeRepos replays | 86400000 (a day, as the reference’s) |
PDS_CACHE_BYTES | the most the server holds in memory of accounts’ state and data read from disk, beyond what each account costs (below) | 268435456 (256 MiB) |