This page documents every field available in your project’s nhost.toml, generated
directly from the configuration schema. For task-oriented guidance and copy-paste
examples, see the per-product documentation; this page is the exhaustive field reference.
The root of nhost.toml is made up of the following sections.
Section
Description
global
Global configuration that applies to all services
hasura
Configuration for hasura
graphql
Advanced configuration for GraphQL
functions
Configuration for functions service
auth
Configuration for auth service
postgres
Configuration for postgres service
provider
Configuration for third party providers like SMTP, SMS, etc.
storage
Configuration for storage service
ai
Configuration for graphite service
observability
Configuration for observability service
experimental
Experimental configuration for unreleased services. Subject to breaking changes.
Global configuration that applies to all services
Field
Type
Default
Description
environment
list of GlobalEnvironmentVariable
[]
User-defined environment variables that are spread over all services
Configuration for hasura
Field
Type
Default
Description
version
string
"v2.48.10-ce"
Version of hasura, you can see available versions in the URL below: https://hub.docker.com/r/hasura/graphql-engine/tags
jwtSecrets
list of JWTSecret
JWT Secrets configuration
adminSecret
string
Admin secret
webhookSecret
string
Webhook secret
settings
object
Configuration for hasura services
authHook?
object
Webhook used to authenticate GraphQL requests.
logs
object
Logging configuration for the service.
events
object
Event delivery configuration.
resources?
Resources
Resources for the service
rateLimit?
RateLimit
Rate limiting applied to the service.
Field
Type
Default
Description
corsDomain
list of Url
["*"]
Comma-separated list of domains allowed to make cross-origin requests.
devMode
bool
true
Include detailed error messages in API responses (development only).
enableAllowList
bool
false
Restrict execution to queries in the allowlist.
enableConsole
bool
true
Serve the web console for managing the GraphQL API.
enableRemoteSchemaPermissions
bool
false
Enforce role-based permissions on remote schemas.
enabledAPIs
list of HasuraAPIs
["metadata", "graphql", "pgdump", "config"]
Comma-separated list of APIs to expose (e.g. metadata, graphql).
inferFunctionPermissions
bool
true
Automatically infer permissions for custom SQL functions.
liveQueriesMultiplexedRefetchInterval
uint32
1000
How often, in milliseconds, live queries are refetched.
stringifyNumericTypes
bool
false
Return numeric and bigint values as strings to avoid precision loss.
Optional.
Field
Type
Default
Description
url
string
URL of the webhook used to authenticate requests.
mode
"GET" | "POST"
"POST"
HTTP method used to call the auth webhook (GET or POST).
sendRequestBody
bool
true
Forward the request body to the auth webhook.
Field
Type
Default
Description
level
"debug" | "info" | "error" | "warn"
"warn"
Minimum severity of log messages to emit.
Field
Type
Default
Description
httpPoolSize
uint32 & >=1 & <=100
100
Maximum number of concurrent HTTP connections used to deliver events.
Optional. Advanced configuration for GraphQL
Field
Type
Default
Description
security
GraphqlSecurity
Security controls for the GraphQL API.
Configuration for functions service
Field
Type
Default
Description
node
object
Node.js runtime configuration for functions.
resources?
object
Compute resources and scaling for the service.
rateLimit?
RateLimit
Rate limiting applied to the service.
Field
Type
Default
Description
version
20 | 22
22
Version of the service image to deploy.
Optional.
Field
Type
Default
Description
networking?
Networking
Network exposure and ingress configuration.
Configuration for auth service
Field
Type
Default
Description
version
string
"0.49.1"
Version of auth, you can see available versions in the URL below: https://hub.docker.com/r/nhost/hasura-auth/tags Releases: https://github.com/nhost/hasura-auth/releases
resources?
Resources
Resources for the service
elevatedPrivileges
object
Settings for elevated-privilege operations.
redirections
object
Allowed post-authentication redirect URLs.
signUp
object
User sign-up settings.
user
object
Default settings applied to users.
session
object
Access and refresh token settings.
method
object
Available authentication methods.
totp
object
Time-based one-time password (TOTP) authentication.
oauth2Provider
object
Settings for acting as an OAuth 2.0 provider.
misc
object
Miscellaneous authentication settings.
rateLimit
AuthRateLimit
Rate limiting applied to the service.
Field
Type
Default
Description
mode
"recommended" | "required" | "disabled"
"disabled"
How elevated privileges are granted.
Field
Type
Default
Description
clientUrl
Url
"http://localhost:3000"
URL of your frontend application, used for post-authentication redirects.
allowedUrls
list of string
Additional URLs permitted as post-authentication redirect targets.
Field
Type
Default
Description
enabled
bool
true
Inverse of AUTH_DISABLE_SIGNUP
disableNewUsers
bool
false
Block newly registered users from signing in until activated.
disableAutoSignup
bool
false
Require explicit account creation instead of signing users up on first login.
turnstile?
object
Cloudflare Turnstile bot-protection settings.
Optional.
Field
Type
Default
Description
secretKey
string
Secret key used to verify Turnstile tokens.
Field
Type
Default
Description
roles
object
Default and allowed roles for users.
locale
object
Default and allowed locales for users.
gravatar
object
Gravatar avatar settings.
email
object
Restrictions on which email addresses may sign up.
emailDomains
object
Allowed and blocked email domains for sign-up.
Field
Type
Default
Description
default
UserRole
"user"
Default role assigned to new users.
allowed
list of UserRole
[default, "me"]
Roles a user is allowed to assume.
Field
Type
Default
Description
default
Locale
"en"
Default locale used for emails and messages.
allowed
list of Locale
[default]
Locales users are allowed to select.
Field
Type
Default
Description
enabled
bool
true
Use Gravatar to provide default user avatars.
default
"404" | "mp" | "identicon" | "monsterid" | "wavatar" | "retro" | "robohash" | "blank"
"blank"
Fallback Gravatar image used when a user has none.
rating
"pg" | "r" | "x" | "g"
"g"
Maximum Gravatar content rating to allow.
Field
Type
Default
Description
allowed
list of Email
Email addresses permitted to sign up.
blocked
list of Email
Email addresses blocked from signing up.
Field
Type
Default
Description
allowed
list of string & net.FQDN
Email domains permitted to sign up.
blocked
list of string & net.FQDN
Email domains blocked from signing up.
Field
Type
Default
Description
accessToken
object
Access token settings.
refreshToken
object
Refresh token settings.
Field
Type
Default
Description
expiresIn
uint32
900
Lifetime of an access token, in seconds.
customClaims
list of object
[]
Custom claims added to the JWT, mapped from the session and database.
Field
Type
Default
Description
expiresIn
uint32
2592000
Lifetime of a refresh token, in seconds.
Field
Type
Default
Description
anonymous
object
Anonymous (guest) sign-in.
emailPasswordless
object
Passwordless sign-in via email magic link.
otp
object
One-time password (OTP) sign-in.
emailPassword
object
Email and password sign-in.
smsPasswordless
object
Passwordless sign-in via SMS.
oauth
object
OAuth social sign-in providers.
webauthn
object
WebAuthn / passkey sign-in.
Field
Type
Default
Description
enabled
bool
false
Enable this feature.
Field
Type
Default
Description
enabled
bool
false
Enable this feature.
Field
Type
Default
Description
email
object
Enable one-time-password sign-in over email.
Field
Type
Default
Description
enabled
bool
false
Enable this feature.
Field
Type
Default
Description
hibpEnabled
bool
false
Disabling email+password sign in is not implmented yet enabled: bool | *true
emailVerificationRequired
bool
true
Require users to verify their email before signing in.
passwordMinLength
uint8 & >=3
9
Minimum allowed password length.
Field
Type
Default
Description
enabled
bool
false
Enable this feature.
Field
Type
Default
Description
enabled
bool
false
Enable this feature.
clientId
string
(conditional) Client id
keyId
string
(conditional) Key id
teamId
string
(conditional) Team id
privateKey
string
(conditional) Private key
audience?
string
Expected audience claim for the provider’s tokens.
scope?
list of string
OAuth scopes requested from the provider.
Includes all fields from StandardOauthProvider .
Field
Type
Default
Description
tenant
string
"common"
Directory (tenant) ID for the provider.
Includes all fields from StandardOauthProvider .
Field
Type
Default
Description
tenant
string
"common"
Directory (tenant) ID for the provider.
Field
Type
Default
Description
enabled
bool
false
Enable this feature.
consumerKey
string
(conditional) Consumer key
consumerSecret
string
(conditional) Consumer secret
Includes all fields from StandardOauthProvider .
Field
Type
Default
Description
connection?
string
Specific connection to use for the provider.
organization?
string
Organization identifier for the provider.
Field
Type
Default
Description
enabled
bool
false
Enable this feature.
relyingParty?
object
WebAuthn relying party settings.
attestation
object
WebAuthn attestation conveyance settings.
Optional.
Field
Type
Default
Description
id
string
""
Relying party identifier (typically your domain).
name?
string
Human-readable relying party name.
origins?
list of Url
[redirections.clientUrl]
Allowed origins for WebAuthn ceremonies.
Field
Type
Default
Description
timeout
uint32
60000
Timeout, in milliseconds, for WebAuthn ceremonies.
Field
Type
Default
Description
enabled
bool
false
Enable this feature.
issuer
string
(conditional) Issuer
Field
Type
Default
Description
enabled
bool
false
Enable this feature.
loginURL
string
(conditional) Login url
accessToken
object
Access token settings.
refreshToken
object
Refresh token settings.
clientIdMetadataDocument
object
Client ID metadata document settings.
Field
Type
Default
Description
expiresIn
uint32
900
Token lifetime, in seconds.
Field
Type
Default
Description
expiresIn
uint32
2592000
Token lifetime, in seconds.
Field
Type
Default
Description
enabled
bool
false
Enable this feature.
Field
Type
Default
Description
concealErrors
bool
false
Hide detailed error messages from API responses.
Configuration for postgres service
Field
Type
Default
Description
version
string
"14.20-20251217-1"
Version of postgres, you can see available versions in the URL below: https://hub.docker.com/r/nhost/postgres/tags
resources
object
Resources for the service
settings?
object
Advanced configuration settings for the service.
pitr?
object
Point-in-time recovery settings.
Field
Type
Default
Description
compute?
ResourcesCompute
CPU and memory allocation.
storage
object
Persistent disk storage.
replicas?
1
Number of service replicas to run.
enablePublicAccess?
bool
false
Expose the database on a public endpoint.
allowedCIDRs?
[...net.IPCIDR] & list.MaxItems(3)
CIDR prefixes for IP-based access control. When set, only connections from these CIDRs are allowed. When unset, all IPs are allowed. Only effective when enablePublicAccess is true.
Field
Type
Default
Description
capacity
uint32 & >=1 & <=4000
Storage capacity, in gigabytes.
Optional.
Field
Type
Default
Description
jit
"off" | "on"
"on"
Enable just-in-time compilation of queries.
maxConnections
int32
100
Maximum number of concurrent database connections.
sharedBuffers
string
"128MB"
Memory dedicated to the shared buffer cache.
effectiveCacheSize
string
"4GB"
Planner estimate of memory available for disk caching.
maintenanceWorkMem
string
"64MB"
Memory used for maintenance operations such as VACUUM.
checkpointCompletionTarget
number
0.9
Target fraction of the checkpoint interval over which to spread writes.
walBuffers
string
"-1"
Memory used for write-ahead log buffers.
defaultStatisticsTarget
int32
100
Default sample size for table statistics.
randomPageCost
number
4.0
Planner’s estimated cost of a non-sequential disk page fetch.
effectiveIOConcurrency
int32
1
Number of concurrent disk I/O operations the planner expects.
workMem
string
"4MB"
Memory used per query operation before spilling to disk.
hugePages
string
"try"
Whether to use huge memory pages.
minWalSize
string
"80MB"
Minimum size to shrink the write-ahead log to.
maxWalSize
string
"1GB"
Maximum write-ahead log size before a checkpoint is triggered.
maxWorkerProcesses
int32
8
Maximum number of background worker processes.
maxParallelWorkersPerGather
int32
2
Maximum parallel workers per Gather node.
maxParallelWorkers
int32
8
Maximum parallel workers across the system.
maxParallelMaintenanceWorkers
int32
2
Maximum parallel workers for maintenance operations.
walLevel
string
"replica"
Amount of information written to the write-ahead log.
maxWalSenders
int32
10
Maximum number of concurrent WAL sender processes.
maxReplicationSlots
int32
10
Maximum number of replication slots.
archiveTimeout
int32 & >=300 & <=1073741823
300
Force a WAL segment switch after this many seconds.
trackIoTiming
"on" | "off"
"off"
Collect timing statistics for disk I/O.
Optional.
Field
Type
Default
Description
retention
uint8 & 7
Number of days to retain backups.
Configuration for third party providers like SMTP, SMS, etc.
Field
Type
Default
Description
smtp?
Smtp
SMTP server used to send emails.
sms?
Sms
SMS provider configuration.
Configuration for storage service
Optional.
Field
Type
Default
Description
server
"tcp://run-clamav:3310"
Address of the antivirus (ClamAV) server.
Optional. Configuration for graphite service
Field
Type
Default
Description
version
string
"0.8.1"
Version of the service image to deploy.
resources
object
Compute resources and scaling for the service.
openai
object
OpenAI API configuration.
autoEmbeddings
object
Automatic embeddings generation settings.
webhookSecret
string
Secret used to authenticate webhook calls.
Field
Type
Default
Description
compute
ComputeResources
CPU and memory allocation.
Field
Type
Default
Description
organization?
string
Organization identifier for the provider.
apiKey
string
API key used to authenticate with the service.
Field
Type
Default
Description
synchPeriodMinutes
uint32
5
How often, in minutes, embeddings are synchronized.
Configuration for observability service
Field
Type
Default
Description
grafana
Grafana
Grafana dashboards and alerting configuration.
Optional. Experimental configuration for unreleased services. Subject to breaking changes.
Field
Type
Default
Description
constellation?
Constellation
Constellation GraphQL engine settings.
Types reused across multiple sections above.
Field
Type
Default
Description
name
=~"(?i)^[a-z_]{1,}[a-z0-9_]*" & !~"(?i)^NHOST_" & !~"(?i)^HASURA_"
Name of the environment variable
value
string
Value of the environment variable
Signing key and configuration used to verify JSON Web Tokens. See JSON Web Tokens for the full configuration and examples.
type : " HS384 " | " HS512 " | * " HS256 "
type : " RS256 " | " RS384 " | " RS512 "
claims_format ?: " stringified_json " | * " json "
claims_map ?: [... #ClaimMap ]
claims_namespace : string | * " https://hasura.io/jwt/claims "
claims_namespace_path : string
Resource configuration for a service
Field
Type
Default
Description
compute?
ResourcesCompute
CPU and memory allocation.
replicas
uint8 & >=1 & <=10
1
Number of replicas for a service
autoscaler?
Autoscaler
Automatic replica scaling settings.
networking?
Networking | null
Network exposure and ingress configuration.
Field
Type
Default
Description
limit
uint32
Maximum number of requests allowed per interval.
interval
string & time.Duration
Length of the rate-limit window.
APIs for hasura
" metadata " | " graphql " | " pgdump " | " config "
Field
Type
Default
Description
forbidAminSecret
bool
false
Reject requests authenticated with the admin secret.
maxDepthQueries
uint
0
Maximum allowed depth of a GraphQL query.
Field
Type
Default
Description
ingresses
list of Ingress
[]
Ingress rules exposing the service.
Field
Type
Default
Description
emails
RateLimit
{limit: 10, interval: "1h"}
Rate limit for outgoing emails.
sms
RateLimit
{limit: 10, interval: "1h"}
Rate limit for outgoing SMS messages.
bruteForce
RateLimit
{limit: 10, interval: "5m"}
Rate limit to mitigate brute-force attacks.
signups
RateLimit
{limit: 10, interval: "5m"}
Rate limit for new sign-ups.
global
RateLimit
{limit: 100, interval: "1m"}
Global rate limit applied across all auth endpoints.
oauth2Server
RateLimit
{limit: 100, interval: "5m"}
Rate limit for OAuth 2.0 server endpoints.
string & strings. MinRunes ( 2 ) & strings. MaxRunes ( 3 )
=~ " ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?: \\ .[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$ "
Field
Type
Default
Description
enabled
bool
false
Enable this feature.
clientId
string
(conditional) Client id
clientSecret
string
(conditional) Client secret
Field
Type
Default
Description
enabled
bool
false
Enable this feature.
clientId
string
(conditional) Client id
clientSecret
string
(conditional) Client secret
audience?
string
Expected audience claim for the provider’s tokens.
scope?
list of string
OAuth scopes requested from the provider.
Field
Type
Default
Description
cpu
uint32 & >=250 & <=30000
milicpus, 1000 milicpus = 1 cpu
memory
uint32 & >=128 & <=62464
MiB: 128MiB to 30GiB
// these are needed for backwards compatibility, they're actually ignored
method ?: " LOGIN " | " CRAM-MD5 " | " PLAIN "
host : string & != " postmark " & ( net . FQDN | net . IP )
method : " LOGIN " | " CRAM-MD5 " | " PLAIN "
Field
Type
Default
Description
provider
"twilio"
SMS provider to use.
accountSid
string
Provider account SID.
authToken
string
Provider auth token.
messagingServiceId
string
Provider messaging service ID.
Resource configuration for a service
Field
Type
Default
Description
cpu
uint32 & >=62 & <=14000
milicpus, 1000 milicpus = 1 cpu
memory
uint32 & >=128 & <=28720
MiB: 128MiB to 30GiB
Field
Type
Default
Description
adminPassword
string
Admin password for Grafana.
smtp?
object
SMTP server used to send emails.
alerting
object
Grafana alerting configuration.
contacts
object
Contact points for Grafana alerts.
Optional.
Field
Type
Default
Description
host
string & net.FQDN | net.IP
SMTP server hostname.
port
Port
SMTP server port.
sender
string
From address for outgoing emails.
user
string
Username for SMTP authentication.
password
string
Password for SMTP authentication.
Field
Type
Default
Description
enabled
bool
false
Enable this feature.
Field
Type
Default
Description
emails?
list of string
Email addresses to send alerts to.
pagerduty?
list of object
PagerDuty alert contact.
discord?
list of object
Discord OAuth provider.
slack?
list of object
Slack alert contact.
webhook?
list of object
Webhook alert contact.
Optional.
Field
Type
Default
Description
corsAllowedOrigins?
list of string
CORS allowed origins. If set, these are used as-is. If unset, origins are derived from auth.redirections.clientUrl and auth.redirections.allowedUrls (paths/queries/fragments stripped).
debug
bool
false
Enable debug logging.
devMode
bool
false
Return raw connector/database error detail to clients instead of the sanitized generic message. For development only — never enable in production, as it leaks internal schema and data values.
subscriptionPollInterval
string & time.Duration
"1s"
Polling interval for GraphQL subscriptions.
Field
Type
Default
Description
maxReplicas
uint8 & >=2 & <=100
Maximum number of replicas the autoscaler may create.
Field
Type
Default
Description
fqdn
list of string & net.FQDN & strings.MinRunes(1) & strings.MaxRunes(63)
Fully-qualified domain names for the ingress.
tls?
object
TLS configuration for the ingress.
Optional.
Field
Type
Default
Description
clientCA?
string
Client certificate authority for mutual TLS.