Skip to content

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.

VariableDescriptionDefault
PDS_PORTthe port to listen onrequired
PDS_BIND_ADDRESSthe 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 too127.0.0.1
PDS_DATA_DIRa directory for its data: empty the first time, and the server’s own afterrequired
VariableDescription
PDS_HOSTNAMEthe server’s hostname; the server’s DID is did:web:<hostname>
PDS_PUBLIC_URLthe URL its DID documents name as the account’s PDS
PDS_HANDLE_DOMAINSthe domains handles may end in, comma-separated, each with its leading dot, such as .test
PDS_PLC_URLthe PLC directory it registers DIDs with
PDS_PLC_ROTATION_KEY_HEXits secp256k1 PLC rotation key, 32 bytes as hex
PDS_RECOVERY_DID_KEYoptional: a did:key listed before the server’s own as a rotation key of every DID it creates
VariableDescriptionDefault
PDS_BLOBSTORE_S3_BUCKETthe bucket; unset, blobs are kept in PDS_DATA_DIRunset
PDS_BLOBSTORE_S3_REGIONthe region requests to the store are signed forus-east-1
PDS_BLOBSTORE_S3_ENDPOINTthe 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.comunset
PDS_BLOBSTORE_S3_FORCE_PATH_STYLEtrue: 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_KEYthe 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 setunset
PDS_BLOBSTORE_S3_UPLOAD_TIMEOUT_MShow long storing one upload may take, in milliseconds20000
PDS_BLOBSTORE_S3_REQUEST_TIMEOUT_MShow long any other request to the store may take, in milliseconds10000
VariableDescription
PDS_URLthe server’s base URL
PDS_TOKENa bearer token to send, if set
PDS_ADMIN_PASSWORDwith no PDS_TOKEN, the admin’s password, sent as Basic with the user admin
VariableDescriptionDefault
PDS_SYNChow 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 sharetogether
VariableDescription
PDS_EMAIL_SMTP_URLthe 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_FROMthe address each email is from
VariableDescription
PDS_DEV_MAIL_DIRoptional: a directory each email is also written to, for tests
VariableDescription
PDS_CRAWLERSoptional: the base URLs of the crawlers (relays) to notify, comma-separated, such as http://127.0.0.1:2470
VariableDescriptionDefault
PDS_HANDLE_DNS_SERVERthe 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]:5353unset: the system’s resolver
PDS_HANDLE_FETCHfor 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
VariableDescriptionDefault
PDS_INVITE_REQUIREDtrue or false: whether createAccount needs an invite codefalse
PDS_ADMIN_PASSWORDthe password of the admin methods’ Basic auth; unset or empty, no request is the adminunset
PDS_RATE_LIMITS_ENABLEDtrue or false: whether the rate limits below applytrue
PDS_BLOB_QUOTA_BYTESthe bytes of blobs an account may hold1073741824 (1 GiB)
PDS_BLOB_TTL_SECShow long an upload no record references is held3600
PDS_BLOB_UPLOAD_LIMITthe 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 blobUploadLimit5242880 (5 MiB, the reference’s)
PDS_MIN_FREE_BYTESthe free space below which writes are refused268435456 (256 MiB)
PDS_MAX_REPO_IMPORT_SIZEthe 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’ repositories314572800 (300 MiB)
PDS_DID_CACHE_SECShow 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_SECShow 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_PROXIESthe 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, noneunset
VariableDescription
PDS_OAUTH_CLIENT_FETCHfor development and testing only: the origins whose client documents and JWKS are fetched from another base URL, as below
VariableDescription
PDS_LEXICON_AUTHORITY_DIDoptional: 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
VariableDescriptionDefault
PDS_LOG_LEVELthe least level of log line written: debug, info, warn or error; or off, for noneinfo
PDS_LOG_DIRa 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 outputunset
PDS_LOG_KEEP_BYTESthe most bytes the files in PDS_LOG_DIR take together; at least 6553667108864 (64 MiB)
PDS_METRICS_PORTthe port /metrics is served on, on 127.0.0.1; unset, metrics are not servedunset
OTEL_EXPORTER_OTLP_ENDPOINTthe 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 oneunset
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTthe URL traces are posted to, as it is; before OTEL_EXPORTER_OTLP_ENDPOINTunset
OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_TRACES_PROTOCOLhttp/protobuf, the only protocol the server speakshttp/protobuf
OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERSheaders sent with each export, key=value pairs joined by ,, each value percent-decoded; the second’s pairs winnone
OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_TRACES_COMPRESSIONgzip or nonenone
OTEL_SERVICE_NAMEthe service.name of the server’s spansunknown_service:pds
OTEL_SDK_DISABLEDtrue turns traces off, whatever else is setfalse
OTEL_BSP_SCHEDULE_DELAYmilliseconds between exports5000
OTEL_BSP_MAX_QUEUE_SIZEspans held for export at most; past it, new spans are dropped2048
OTEL_BSP_MAX_EXPORT_BATCH_SIZEspans in one export at most512
OTEL_BSP_EXPORT_TIMEOUTmilliseconds an export may take, retries and all, before its spans are dropped30000
VariableDescription
PDS_BSKY_APP_VIEW_URLthe default AppView’s URL, such as https://api.bsky.app
PDS_BSKY_APP_VIEW_DIDits DID, such as did:web:api.bsky.app
PDS_BSKY_APP_VIEW_CDN_URL_PATTERNoptional: 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_PROTECTIONoptional: 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)
VariableDescription
PDS_DISABLE_SSRF_PROTECTIONas 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
VariableDescriptionDefault
PDS_REPO_BACKFILL_LIMIT_MSthe backfill window W: how far back, in milliseconds, subscribeRepos replays86400000 (a day, as the reference’s)
PDS_CACHE_BYTESthe most the server holds in memory of accounts’ state and data read from disk, beyond what each account costs (below)268435456 (256 MiB)