pocketone.yaml reference

Every section the pocketone binary understands, from pocketone config --json. Each extension owns its own section. pocketone config check checks a file. How the file works (where it's found, .env secrets) is on the Config page.

app:

The single app: data dir, dev mode, encryption, hooks, migrations, public dir, and the .env names it may read (env_allow). Not used when a provider runs many instances.

Key	Type	Default	Description
dir	string		The data folder (pb_data). Default: pb_data next to the executable. The --dir flag wins.
dev	bool		Dev mode: logs and SQL statements printed to the console. The --dev flag wins.
encryption_env	string		Name of the environment variable holding a 32-character key that encrypts the app settings. The --encryptionEnv flag wins.
query_timeout	duration		Default timeout for SELECT queries, such as 30s. The --queryTimeout flag wins.
hooks_dir	string		The JS hooks folder. Default: pb_hooks next to pb_data. The --hooksDir flag wins.
hooks_watch	bool		Restart the app when a pb_hooks file changes. On unless false. The --hooksWatch flag wins.
hooks_pool	int		How many JS runtimes are kept ready for hooks. Default 15. The --hooksPool flag wins.
migrations_dir	string		The migrations folder. Default: pb_migrations next to pb_data. The --migrationsDir flag wins.
automigrate	bool		Write a migration file when you change collections in the dashboard. On unless false. The --automigrate flag wins.
public_dir	string		The static files folder. Default: pb_public next to the executable. The --publicDir flag wins.
index_fallback	bool		Serve index.html for a missing static path, for single-page apps. On unless false. The --indexFallback flag wins.
env_allow	list of string		Names from the .env the app and its JS hooks may read. Default none.

autotls:

Automatic HTTPS certificates (ACME): auto, email, CA, domains, DNS-01, certificate storage. The --autotls* flags win.

Key	Type	Default	Description
auto	bool		Get certificates through ACME (CertMagic). Flag: --autotls.
email	string		ACME account email, for expiry notices from the CA. Flag: --autotlsEmail.
ca	string		letsencrypt (default), letsencrypt-staging, zerossl, or an ACME directory URL. Flag: --autotlsCA.
storage	string		Where certificates are kept. Default pb_data/.autotls.
domains	list of string		Extra domains to get at start; wildcards (*.example.com) need dns. Flag: --autotlsDomains.
dns.provider	string		DNS provider for DNS-01 challenges (needed for wildcards): cloudflare. Flag: --autotlsDNS.
dns.api_token	string		The provider's API token. Write $VAR to read it from the .env beside the file.
dns.api_token_env	string		Or: the environment variable holding the token. Default CF_API_TOKEN. Flag: --autotlsDNSTokenEnv.

Owned by Auto TLS.

docker:

Runtime provider docker: each instance in its own container with the PocketBase (pb:) or PocketOne (p1:) binary of its version (image, binary cache and manifest, instance root, default version, idle stop, limits).

Key	Type	Default	Description
socket	string		The Docker socket. Default $DOCKER_HOST when it is unix://, else /var/run/docker.sock.
image	string		Base image the binaries run in, such as alpine:3.20. Required; pulled when missing.
binaries	string		Folder of the release binary cache and its releases.json. Required.
versions	list of string		The minors this host serves, such as pb:0.36 or p1:0.0 (latest patch of each, from docker update).
root	string		Folder with one folder per instance (/). Required.
home	string		The instance folder inside the container. Default /home/pockethost.
default_version	string		Version for instances that name none, such as p1:0.0.*. Empty: such instances fail.
min_upstream	string		Oldest upstream PocketBase release served. Default 0.23.0; lower it only for releases you cache yourself.
idle_ttl	duration		Stop a container after this long without requests. Default 10m.
max_concurrent_starts	int		Containers starting at once. Default 4.
start_timeout	duration		How long a container gets to answer its health check. Default 60s.
nano_cpus	int		CPU limit per container in billionths of a CPU (1000000000 = one CPU). 0: no limit.
pids_limit	int		Process limit per container. 0: Docker's default.
nofile	list of int		Open-file limit per container: [soft, hard]. Empty: Docker's default.
cap_drop	list of string		Linux capabilities to drop, such as [ALL].
no_new_privileges	bool		Set no-new-privileges on every container.
network	string		Docker network for the containers. Default the bridge.
adopt_image	string		Also adopt running unlabeled containers of this image named after an instance id (taking over from another manager).

Owned by Docker.

edges:

The fleet: this edge's id and a fixed list of the other edges (id, internal_url, region).

Key	Type	Default	Description
self	string		This edge's id, such as lax-1.
list	list of object		The other edges: id, internal_url (where this edge reaches it) and optional region.

Owned by Edge.

firewall:

Peers allowed to connect, trusted proxies and client-IP headers, trusted clients, the rate-limit header prefix. Turns the firewall on.

Key	Type	Default	Description
allow_cidrs	list of string		Peers (IPs or CIDRs) allowed to connect; others get 403. Empty: everyone.
trusted_proxies	list of string		Peers whose client-IP headers are believed.
client_ip_headers	list of string		Headers read, in order, for the client IP from a trusted proxy. Default CF-Connecting-IP, True-Client-IP, X-Forwarded-For, X-Real-IP.
trusted_clients	list of string		Client IPs or CIDRs that get the trusted rate limits on every instance.
trusted_client_headers	list of string		Headers a trusted client uses to name its end user's IP, so each user gets their own limits. Default X-Client-IP.
rate_limit_header_prefix	string		Prefix of the rate-limit response headers. Default X-RateLimit.

Owned by Firewall.

instances:

Where a multi-instance host's instances come from (a YAML file), and dev mode (serve unknown hostnames).

Key	Type	Default	Description
file	string	instances.yaml	The instances file (id, hosts and settings for each instance), reloaded when it changes.
dev	bool		Also serve unknown hostnames: each becomes an instance named after it, in dev mode, with its folder made on first use.

Owned by Multisite.

lifecycle:

Instance data on this host: how often disk use is measured and last-request times are reported.

Key	Type	Default	Description
measure_every	duration	24h0m0s	How old an instance's disk measurement may get before it is measured again. Default 24h.
report_every	duration	1h0m0s	How often changed last-request times are reported to the sink. Default 1h.
concurrency	int	2	How many instances are measured at once. Default 2.

Owned by Stats.

mothership:

A community mothership to mirror instances and edges from: url, login, this edge's id, internal URL, region, apex.

Key	Type	Default	Description
url	string		The mothership's URL. Required.
email	string		Superuser email this edge logs in with; use a $VAR from the .env.
password	string		Superuser password; use a $VAR from the .env.
self	string		This edge's edge_id, such as lax-1. Default: the edges section's self. Required.
internal_url	string		Where other edges reach this one. Set: the edge registers itself when the mothership has no record for it.
region	string		Region recorded when the edge registers itself.
apex	string		Makes . a hostname of every instance. Empty: hosts only.
heartbeat	duration		How often this edge marks itself online. Default 15s; negative: never.
resync	duration		How often everything is reloaded, in case a change was missed. Default 10m.

Owned by Mothership.

pitr:

Point-in-time restore: on by default, retention, snapshot interval. The --pitr and --pitrRetention flags win.

Key	Type	Default	Description
enabled	bool		On unless false. The --pitr flag wins.
retention	duration		How far back a restore can go. Default 72h. The --pitrRetention flag wins.
snapshot_interval	duration		How often a full copy is taken. Default 24h. Shorter: faster restores, more storage.

Owned by PITR.

pocker:

Runtime provider pocker: instances run in-process (root folder, hooks pool, egress allow list, instance limit defaults).

Key	Type	Default	Description
root	string	./pb_root	The folder holding one folder per instance: /.
hooks_pool_size	int	2	JS runtimes kept ready per instance (0: a new one for each hook run).
max_js_execution	duration	30s	Longest any single JS call (hook, route, cron job, migration) may run.
max_js_allocation	int	67108864	Largest result a JS built-in may allocate in one step, such as 64MiB.
max_call_stack_size	int	2000	Deepest JS recursion allowed.
max_sleep	duration	10s	Longest a JS sleep() call may wait.
max_query_duration	duration	30s	Longest an SQL statement without its own deadline may run.
http_send_max_timeout	duration	1m0s	Longest timeout a JS $http.send call may use.
http_send_max_body	int	10485760	Largest response body a JS $http.send call may read, such as 10MiB.
max_concurrent_js	int	16	JS calls an instance runs at once; more wait up to max_js_execution, then fail.
egress_allow	list of string		Private networks (CIDRs) instances may still connect to. Default none: public addresses only.

Owned by Pocker.

provider:

The runtime provider that runs many instances (pocker or docker). Omit for a single stock app.

rate_limits:

Default rate limits for every instance (per instance: extensions.firewall.rate_limits). Turns the firewall on.

Key	Type	Default	Description
ip_hourly	int		Requests per hour from one client IP to one instance. Default 1000.
instance_hourly	int		Requests per hour to one instance from everyone. Default 10000.
ip_concurrent	int		Requests one client IP may have open on one instance at once. Default 15.
instance_concurrent	int		Requests one instance may have open at once. Default 250.
file_weight	number		What a /api/files request costs, as a share of a request. Default 0.1.
trusted.ip_hourly	int		Requests per hour from one trusted client IP to one instance.
trusted.instance_hourly	int		Requests per hour to one instance.
trusted.ip_concurrent	int		Requests one trusted client IP may have open on one instance at once.
trusted.instance_concurrent	int		Requests one instance may have open at once.
off	bool		No rate limiting. The default in dev mode unless rate_limits is set.

Owned by Firewall.

s3redirect:

Signed S3 redirects for file downloads: enabled, URL lifetime. The --s3Redirect and --s3RedirectTTL flags win.

Key	Type	Default	Description
enabled	bool		On unless false (it only acts when S3 file storage is on). Flag: --s3Redirect.
ttl	duration		How long each signed URL stays valid. Default 5m, max 7 days. Flag: --s3RedirectTTL.

Owned by S3 Redirect.

server:

How the binary listens: http, https and CORS origins (single-app mode: the serve command's defaults).

Key	Type	Default	Description
http	string		Plain HTTP address, such as 127.0.0.1:8090. Single app: the --http default (the flag wins). Many instances: redirects to https when https is set.
https	string		HTTPS address. Single app: the --https default (the flag wins). Many instances: the main address.
origins	list of string		Allowed CORS origins. Single app: the --origins default (the flag wins).
plain	list of string		Many instances only: extra plain HTTP addresses with no redirect.
tls.cert	string		Many instances only: the certificate file, reloaded when it changes.
tls.key	string		Many instances only: the private key file, reloaded when it changes.
shutdown_timeout	duration		Many instances only: how long in-flight requests get to finish at stop.