Skip to content
SupportDashboard

Configuration Reference

Full reference for the nhost.toml configuration file, generated from the configuration schema.

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
apple object Apple OAuth provider.
azuread object Azure AD OAuth provider.
bitbucket StandardOauthProvider Bitbucket OAuth provider.
discord StandardOauthProviderWithScope Discord OAuth provider.
entraid object Microsoft Entra ID OAuth provider.
facebook StandardOauthProviderWithScope Facebook OAuth provider.
github StandardOauthProviderWithScope GitHub OAuth provider.
gitlab StandardOauthProviderWithScope GitLab OAuth provider.
google StandardOauthProviderWithScope Google OAuth provider.
linkedin StandardOauthProviderWithScope LinkedIn OAuth provider.
spotify StandardOauthProviderWithScope Spotify OAuth provider.
strava StandardOauthProviderWithScope Strava OAuth provider.
twitch StandardOauthProviderWithScope Twitch OAuth provider.
twitter object Twitter (X) OAuth provider.
windowslive StandardOauthProviderWithScope Microsoft account (Windows Live) OAuth provider.
workos object WorkOS OAuth provider.
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.

auth.oauth2Provider.clientIdMetadataDocument

Section titled “auth.oauth2Provider.clientIdMetadataDocument”
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

Field Type Default Description
version string "0.14.0" Version of storage service, you can see available versions in the URL below: https://hub.docker.com/r/nhost/hasura-storage/tags Releases: https://github.com/nhost/hasura-storage/releases
resources? Resources {networking?: null} Networking (custom domains at the moment) are not allowed as we need to do further configurations in the CDN. We will enable it again in the future.
antivirus? object Antivirus scanning for uploaded files.
rateLimit? RateLimit Rate limiting applied to the 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"
key: string
} |
{
type: "RS256" | "RS384" | "RS512"
key: string
signingKey?: string
kid?: string
} |
{
jwk_url: #Url | *null
}) &
{
claims_format?: "stringified_json" | *"json"
audience?: string
issuer?: string
allowed_skew?: uint32
header?: string
} & {
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.
string

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
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
{
host: "postmark"
password: string
sender: string
// these are needed for backwards compatibility, they're actually ignored
user?: string
port?: #Port
secure?: bool
method?: "LOGIN" | "CRAM-MD5" | "PLAIN"
} | {
user: string
password: string
sender: string
host: string & !="postmark" & (net.FQDN | net.IP)
port: #Port
secure: bool
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.
Field Type Default Description
version string "0.1.0" Version of constellation, you can see available versions in the URL below: https://hub.docker.com/r/nhost/constellation/tags
settings? object Advanced configuration settings for the service.

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.
uint16