ThimbleDB authorities can be configured through code options and environment settings. Prefer code for collection layouts and indexes because it is easier to type-check and review. Keep secrets in the deployment platform's secret store.
Code options take precedence over matching environment settings.
Both startNodeAuthority() and createCloudflareAuthority() accept:
| Option | Purpose | Default |
|---|---|---|
collectionLayouts |
Explicit trie or snapshot layout by collection |
Trie for collections not listed |
collectionIndexes |
Complete declared secondary-index definitions | No indexes |
collections |
Bounded Studio collection catalogue | Names inferred from configured layouts and indexes |
studio |
Enable Studio APIs and Node asset hosting | false |
studioOrigin |
Additional exact origin accepted for Studio mutations | Local Node authority origin when Studio is enabled; otherwise none |
readBundles |
Advertise bounded decoded point-read bundles | false |
mutationBatches |
Advertise atomic bounded multi-document writes | false |
These settings are supported by both the Node and Cloudflare authorities unless noted otherwise.
| Setting | Purpose | Default or requirement |
|---|---|---|
THIMBLE_MASTER_KEY |
Base64 deployment master key with at least 32 decoded bytes | Required outside the local Node provider; local Node creates a protected key file when absent |
THIMBLE_ALLOWED_ORIGIN |
Exact browser origin accepted for state-changing requests | Required except local Node, which defaults to http://127.0.0.1:5173 |
THIMBLE_PREFIX |
Application prefix inside the data store | demo |
THIMBLE_KEY_VERSION |
Active scope-key version for writes | 1 |
THIMBLE_READ_KEY_VERSIONS |
Comma-separated historical key versions that remain readable | Empty |
THIMBLE_HEAD_TTL_MS |
Browser mutable-HEAD freshness interval, measured from completion of a successful fetch or revalidation | 1000 |
THIMBLE_COLLECTION_LAYOUTS |
Comma-separated `collection=trie | snapshot` mappings |
THIMBLE_COLLECTION_INDEXES |
JSON object containing the complete active index definitions | {} |
THIMBLE_DELETE_RETENTION_DAYS |
Restore window for retained deletions | 30 |
THIMBLE_DELETE_GRACE_DAYS |
Additional delay before expired tombstones leave the live layout | 7 |
THIMBLE_MAINTENANCE_MODE |
Reject normal writes while maintenance is running | false |
THIMBLE_STUDIO |
Enable Studio | false |
THIMBLE_STUDIO_ORIGIN |
Additional exact Studio origin | None, except local Node defaults to its authority origin |
THIMBLE_COLLECTIONS |
Comma-separated Studio collection catalogue | Empty |
THIMBLE_READ_BUNDLES |
Enable the trusted-authority decoded bundle path | false |
THIMBLE_MUTATION_BATCHES |
Enable bounded multi-document mutation requests | false |
THIMBLE_READ_BUNDLES=true changes the read transport trust boundary. Review
Security before enabling it.
THIMBLE_MUTATION_BATCHES=true advertises the batch endpoint through
/api/config. A request is limited to 20 documents and 1 MiB of JSON. The
authority validates the complete request before writing, publishes one
collection revision, and returns only after final HEAD publication. Enabling
the capability does not automatically delay or combine ordinary put()
calls; applications opt in by calling putMany().
Normal EnvelopeObjectStore and browser object-reader instances limit each
decoded object to 16 MiB. This is a code-level safety default rather than an
environment setting. Advanced direct integrations can supply an explicit
maximumDecodedBytes override when constructing those wrappers.
Configure at least one production OIDC provider.
Microsoft Entra:
| Setting | Purpose |
|---|---|
ENTRA_TENANT_ID |
Exact Entra tenant |
ENTRA_AUDIENCE |
API audience |
ENTRA_REQUIRED_SCOPE |
Optional required delegated scope |
ENTRA_REQUIRED_ROLE |
Optional required application role |
Generic OIDC:
| Setting | Purpose |
|---|---|
OIDC_PROVIDER_ID |
Stable route-safe provider identifier |
OIDC_ISSUER |
Exact token issuer |
OIDC_AUDIENCE |
Required audience |
OIDC_JWKS_URI |
HTTPS JWKS endpoint |
OIDC_ALLOWED_TENANTS |
Optional comma-separated tenant allowlist |
OIDC_REQUIRED_SCOPE |
Optional required delegated scope |
OIDC_REQUIRED_ROLE |
Optional required application role |
At least one required scope or role must be configured for each provider. When both are set, both must be present.
| Setting | Purpose | Default |
|---|---|---|
NODE_ENV |
Process mode used to prohibit the local development identity in production | Unset |
THIMBLE_PROVIDER |
Object-store adapter: local, azure, s3, or r2 |
azure when AZURE_STORAGE_CONNECTION_STRING is set; otherwise local |
THIMBLE_HOST |
Authority listen address | 127.0.0.1 |
THIMBLE_PORT |
Authority listen port | 8787 |
THIMBLE_SECURE_COOKIES |
Force Secure session cookies | true for cloud providers; otherwise false unless explicitly enabled |
THIMBLE_SESSION_TTL_SECONDS |
Opaque session lifetime | 3600 |
THIMBLE_AUTH_RATE_LIMIT |
Authentication attempts per durable rate window | 5 |
THIMBLE_AUTH_RATE_WINDOW_MS |
Authentication rate window | 60000 |
THIMBLE_SCOPE_CACHE_MAX |
Maximum cached scope runtimes | 100 |
THIMBLE_SCOPE_CACHE_TTL_MS |
Scope-runtime cache lifetime | 900000 |
THIMBLE_TRUSTED_PROXY_IPS |
Comma-separated immediate proxy addresses trusted for X-Forwarded-For |
Empty |
THIMBLE_DISABLE_IP_RATE_LIMIT |
Disable source-IP limiting when the proxy boundary cannot be verified | false |
| Setting | Purpose | Default |
|---|---|---|
THIMBLE_LOCAL_DATA_ROOT |
Local application-object directory | .thimble-data |
THIMBLE_LOCAL_AUTH_ROOT |
Local authentication-object directory | .thimble-auth |
THIMBLE_LOCAL_SECRET_ROOT |
Local master-key directory | .thimble-data |
THIMBLE_DEV_IDENTITY |
Enable the loopback-only development identity | false |
THIMBLE_DEV_SUBJECT |
Development identity subject | local-developer |
THIMBLE_DEV_DISPLAY_NAME |
Development identity display name | Local developer |
The development identity requires a local provider, a non-production process, a loopback listen host, and loopback application and Studio origins.
Azure Blob Storage:
| Setting | Purpose | Default |
|---|---|---|
AZURE_STORAGE_CONNECTION_STRING |
Server-only Blob Storage connection string | Required |
AZURE_STORAGE_CONTAINER |
Data container | thimbledb |
AZURE_AUTH_STORAGE_CONTAINER |
Authentication container | <data-container>-auth |
Amazon S3:
| Setting | Purpose | Default |
|---|---|---|
S3_BUCKET |
Data bucket | Required |
S3_AUTH_BUCKET |
Authentication bucket | Required |
AWS_REGION |
AWS region used by the SDK | us-east-1 |
S3_ENDPOINT |
Optional S3-compatible endpoint | AWS endpoint |
S3_FORCE_PATH_STYLE |
Use path-style bucket addressing | false |
The AWS SDK uses its normal credential chain.
R2 through the S3 adapter:
| Setting | Purpose |
|---|---|
R2_ACCOUNT_ID |
Cloudflare account ID |
R2_BUCKET |
Data bucket |
R2_AUTH_BUCKET |
Authentication bucket |
R2_ACCESS_KEY_ID |
R2 API access key ID |
R2_SECRET_ACCESS_KEY |
R2 API secret |
Prefer the native Worker bindings for the Cloudflare reference deployment.
| Binding | Purpose | Required |
|---|---|---|
DB |
Private R2 data bucket | Yes |
AUTH_DB |
Separate private R2 authentication bucket | Yes |
ASSETS |
Static application and Studio assets | Optional |
AUTH_RATE_LIMITER |
Native low-latency source-IP rate limit | Optional |
Cloudflare uses a one-hour session lifetime and a bounded in-memory scope runtime cache. Those values are not environment-configurable in the current Worker authority.
The Helm chart maps non-secret config values to the common and Node
environment settings. existingSecret supplies THIMBLE_MASTER_KEY, provider
settings, and any OIDC or workload-identity settings that should not enter a
ConfigMap.
The chart:
- binds
THIMBLE_HOST=0.0.0.0and port8787 - keeps read bundles, mutation batches, Studio, and Ingress opt-in
- validates the local provider as one replica with ephemeral storage
- validates complete generic OIDC settings when that values block is used
- supports additional non-secret settings through
config.extraEnv - supports additional Secret or ConfigMap sources through
extraEnvFrom
See Deploy to Kubernetes for the complete Secret, routing, security, scaling, and upgrade guidance.
These settings apply to command-line maintenance. They are not all authority runtime settings.
| Setting | Purpose |
|---|---|
THIMBLE_SCOPE_ID |
Target scope |
THIMBLE_COLLECTIONS |
Target collection list |
THIMBLE_COLLECTION |
Single collection for a layout migration |
THIMBLE_SOURCE_LAYOUT |
Existing trie or snapshot layout for a layout migration |
THIMBLE_TARGET_LAYOUT |
Replacement trie or snapshot layout for a layout migration |
THIMBLE_COLLECTION_LAYOUTS |
Active layout mapping |
THIMBLE_RETIRED_COLLECTION_LAYOUTS |
Retired layouts eligible for quiescent cleanup |
THIMBLE_COLLECTION_INDEXES |
Complete active index definitions |
THIMBLE_MIGRATION_QUIESCENT |
Confirms writes are blocked for migration commands |
THIMBLE_MAINTENANCE_QUIESCENT |
Confirms writes are blocked for destructive retention maintenance |
Do not add THIMBLE_RETIRED_COLLECTION_LAYOUTS to a Worker and expect it to
perform cleanup. Run the documented maintenance command in a controlled
environment with the matching provider credentials and master key.
The Cloudflare Wrangler example exposes current collection, Studio, and read-bundle settings.
The checked-in Azure and AWS infrastructure templates intentionally expose a smaller core setting set. Their deployment guides list the optional settings that require a reviewed derived template. Do not assume a shell variable is passed into Container Apps or Lambda unless the infrastructure template maps it into the container environment.