Skip to content
Configuration

Configuration

notify is configured with flags and environment variables, interpreted once at start in cmd/notify/config.go. For a flag that also has an environment variable, the order is flag, then environment variable, then default.

Flags use Go’s flag package, so -addr and --addr are the same. Variables marked env only have no flag; some are deliberately not flags because a flag value is visible to every user on the machine through ps.

Commands

CommandPurpose
notify serveRun the API server.
notify bootstrap -org <name> -env <name>Create an organization, an environment and an API key. Prints {"apiKey", "orgId", "envId"} as JSON. Takes -db, -master-key-hex, -dev. Both -org and -env are required.
notify rotate-key -org <name|id> -env <name|id>Mint a new key for an existing scope and revoke every other key for it. Prints the same JSON. An ambiguous name is an error; pass the id. Takes -db, -master-key-hex, -dev. The new key keeps the old one’s permission to attest SMS consent; -attest-sms-consent=true or =false sets it.
notify sms-consent -org <name|id> -env <name|id>Switch operator-attested SMS consent for an existing environment and grant or revoke a key’s permission to attest, without rotating the key. -enable -policy-url https://… turns the setting on (an omitted -policy-url reuses the stored one; it must be https); -disable turns it off and suspends attestations without clearing them. -grant-key <id> and -revoke-key <id> take the key’s id (the SHA-256 shown as apiKeyId, or at least its first 8 characters), never the key itself. With no action it only reports. Always prints {"orgId", "envId", "enabled", "policyUrl", "keys": [{"id", "attestSmsConsent"}]} and logs each change to stderr. Repeating a change is harmless. Takes -db.
notify validate-stepsRe-validate every stored workflow against the current step rules. Read-only; exits 1 if any fail. Takes -db.
notify inboundPipe mode for inbound email. Takes -server, -secret, -timeout.
notify version (also -v, --version)Print the version.

bootstrap and rotate-key must use the same database and master key as serve: the key material is encrypted under it.

serve: core

FlagEnvironment variableDefaultMeaning
-addrNOTIFY_ADDR127.0.0.1:3000HTTP listen address for the API and console.
-dbNOTIFY_DBnotify.dbSQLite database path. Other subcommands read the same variable.
-master-key-hexNOTIFY_MASTER_KEY_HEXnone32 bytes as 64 hex characters. Required unless -dev. Encrypts API keys, integration credentials, session cookies, and environment variables. Prefer the environment variable: a flag value is visible in ps.
-devNOTIFY_DEV (1 or true)offAllow starting with no master key by deriving a fixed, publicly known one. Development only.
NOTIFY_DAGNATS_URLnats://127.0.0.1:4222NATS client URL of the running dagnats. notify does not embed NATS.
NOTIFY_SEEDnotify.seed beside -dbnotify’s program key; must persist. See running notify as a program.
NOTIFY_JOIN_KEYemptyJoin key for registering with a dagnats that has a NATS login.
-nats-urlNOTIFY_NATS_URLemptyDeprecated: used as NOTIFY_DAGNATS_URL when that is unset. Removed in a later release.
-sendmail-commandNOTIFY_SENDMAIL_COMMAND/usr/sbin/sendmail -tiCommand the sendmail email provider pipes each message to. Split on whitespace, run without a shell.
-ssrf-allowNOTIFY_SSRF_ALLOWED_HOSTSemptyComma-separated exact hosts that outbound HTTP may reach even though they resolve to an internal address. Each entry is host (any port) or host:port (that port only; IPv6 as [::1]:3738); prefer the port form. No wildcards. Empty blocks every internal range. A malformed entry stops start.
(env only)NOTIFY_PUBLIC_BASE_URLemptyThe server’s public origin. Used to derive the default Web Push VAPID subject (https://<host>; localhost and IPs yield none), and passed to the console for rendered webhook URLs. Required for SMS inbound texts and delivery status: providers sign the public URL.
(env only)NOTIFY_AGENT_CARDS_DOMAINemptyJetStream domain that holds the chat_cards bucket of agent cards. Empty reads the bucket from the connected dagnats’ own domain. Set it when the bucket lives in another region (see Moving to another dagnats).
(env only)NOTIFY_CONSOLE_READ_ONLYoffExactly 1 disables every mutation in the console.
(env only)NOTIFY_DAGNATS_CONSOLE_URLemptyBase URL of dagnats’ console, as your browser sees it, for run deep-links in Activity.
(env only)NOTIFY_HEALTH_DEGRADED_RATE0.20Integration health: an integration is degraded when more than this share of its deliveries in the window failed. Recipient errors do not count.
(env only)NOTIFY_HEALTH_FAILING_ERRORS3Integration health: this many failed deliveries in the window with no success make an integration failing, as does a credential check the provider rejects.
(env only)NOTIFY_HEALTH_WINDOW1hIntegration health: how far back delivery results count, as a Go duration. A bad value in any of the three stops start.
(env only)NOTIFY_HEALTH_VERIFY_CRON17 6 * * *When the daily credential check runs: a 5-field cron expression, read in UTC. off turns it off and removes its trigger. A malformed value stops start. See Delivery health.

serve: agents

FlagEnvironment variableDefaultMeaning
-mesh-allowNOTIFY_MESH_ALLOWagents.prompt.>Allowlist pattern for the NATS subjects mesh agents are dispatched to.
-mesh-nats-urlNOTIFY_MESH_NATS_URLemptyNATS URL for mesh dispatch, for a hub that is not a dagnats. Empty dispatches over the dagnats program connection.

serve: inbound email

FlagEnvironment variableDefaultMeaning
(env only)NOTIFY_INBOUND_SECRETemptyShared secret the mail forwarder sends as X-Inbound-Secret. Empty makes POST /v1/inbound/email answer 503. Also the default of notify inbound -secret.
(env only)NOTIFY_INBOUND_MX_HOSTemptyThe MX host that inbound domains must point at. Empty uses the placeholder inbound.notify.example.com. Also the SMTP banner name.
-smtpNOTIFY_SMTP_ADDRempty (off)Listen address for the embedded SMTP receiver, e.g. 0.0.0.0:25.
-smtp-certNOTIFY_SMTP_CERTemptyPEM certificate for STARTTLS. Reloaded when it changes. Set with -smtp-key.
-smtp-keyNOTIFY_SMTP_KEYemptyPEM private key. Setting one of -smtp-cert and -smtp-key without the other is an error.

serve: blob store

Environment variableDefaultMeaning
NOTIFY_BLOB_DRIVERempty (off)fs or s3. Anything else stops start.
NOTIFY_BLOB_DIR<directory of NOTIFY_DB>/blobsDirectory for the fs driver.
NOTIFY_BLOB_S3_ENDPOINTnonehost:port, no scheme. Required for s3.
NOTIFY_BLOB_S3_REGIONnoneRegion name.
NOTIFY_BLOB_S3_BUCKETnoneBucket. Required for s3. notify does not create it.
NOTIFY_BLOB_S3_PREFIXnoneKey prefix, to share a bucket.
NOTIFY_BLOB_S3_ACCESS_KEYnoneAccess key.
NOTIFY_BLOB_S3_SECRET_KEYnoneSecret key.
NOTIFY_BLOB_S3_TLSoff1 or true to use HTTPS.

See Blob storage.

serve: chat loop

All env only. See Chat loop.

Environment variableDefaultMeaning
TELEGRAM_BOT_TOKENemptyEnables the Telegram long-poll.
DISCORD_BOT_TOKENemptyEnables the Discord gateway.
NOTIFY_DISCORD_RESPOND_ALLoff1 or true: answer every message in a server channel, not just @-mentions.
NOTIFY_CHAT_DEFAULT_AGENTemptyAgent identifier for cold inbound messages. Empty drops them.
NOTIFY_CHAT_DEFAULT_ORGemptyOrganization id of the default scope.
NOTIFY_CHAT_DEFAULT_ENVemptyEnvironment id of the default scope.

AI workflow builder

All env only. The builder is the console’s Guided create.

Environment variableDefaultMeaning
NOTIFY_AI_API_KEYemptyEnables the builder through an OpenAI-compatible API. Takes priority over ANTHROPIC_API_KEY.
NOTIFY_AI_BASE_URLhttps://openrouter.ai/api/v1Endpoint for the above.
NOTIFY_AI_MODELopenai/gpt-4.1Model for the above.
ANTHROPIC_API_KEYemptyUsed when NOTIFY_AI_API_KEY is unset: Anthropic directly.
NOTIFY_AI_TOKEN_BUDGET300000Token cap for one durable build. 0 disables the cap; an unparsable or negative value uses the default.

With neither key set the builder is disabled.

serve: telemetry and analytics

Environment variableDefaultMeaning
OTEL_EXPORTER_OTLP_ENDPOINTemptyOTLP endpoint. Empty disables tracing completely: nothing is constructed. Setting it also switches log output to structured slog text with trace_id and span_id on records logged inside a span.
OTEL_SERVICE_NAMEnotifyService name on traces.
NOTIFY_DUCKDBnotify-analytics.duckdbDuckDB file for analytics. Only read by a binary built with -tags duckdb; see Observability.
NOTIFY_ANALYTICS_LAKEemptyOff when empty. r2 reads analytics queries from the R2 lake; any other value is a local lake root. Needs -tags duckdb; see Observability.
NOTIFY_LAKE_R2_ENDPOINT, NOTIFY_LAKE_R2_ACCESS_KEY_ID, NOTIFY_LAKE_R2_SECRET_ACCESS_KEYemptyThe R2 lake’s endpoint and credential, for NOTIFY_ANALYTICS_LAKE=r2 and notify analytics-import. Read from the environment only.
NOTIFY_LAKE_BUCKET, NOTIFY_LAKE_PREFIXlode, meshThe R2 lake’s bucket and key prefix.

notify analytics-import

FlagEnvironment variableDefault
-dbNOTIFY_DBnotify.db
-cutoffnone2026-11-08T17:09:48Z (when the live publisher started)
-lakenoner2, or a local lake root directory
-endpointNOTIFY_LAKE_R2_ENDPOINTnone
-bucketNOTIFY_LAKE_BUCKETlode
-prefixNOTIFY_LAKE_PREFIXmesh
-dry-runnoneoff: counts rows per day and writes nothing

The access key and secret come only from NOTIFY_LAKE_R2_ACCESS_KEY_ID and NOTIFY_LAKE_R2_SECRET_ACCESS_KEY, never from a flag, and are never printed.

notify inbound

FlagEnvironment variableDefault
-serverNOTIFY_SERVER_URLhttp://127.0.0.1:3000
-secretNOTIFY_INBOUND_SECRETnone (required)
-timeoutnone30s

Not read by notify

RESEND_API_KEY, TWILIO_*, SIGNALWIRE_*, CF_API_TOKEN, CF_EMAIL_FROM, FIREBASE_* and TELEGRAM_CHAT_ID appear in older notes and deploy scripts. notify serve does not read these. Providers are configured as integrations through the API.