Configuration

All TipOff components are configured via environment variables (12-factor).

Agent

The agent is the component you self-host. It connects to the hosted server and forwards action events to local services.

Core

TIPOFF_AGENT_API_KEY=sk_your_source_key \
TIPOFF_AGENT_GRPC_URL=grpc.tipoff.dev:443 \
TIPOFF_AGENT_ADAPTERS_DIR=./adapters \
./tipoff-agent

Variable	Default	Description
`TIPOFF_AGENT_API_KEY`		Source API key (`sk_...`) — authenticates the gRPC stream
`TIPOFF_AGENT_GRPC_URL`		Server gRPC address (e.g. `grpc.tipoff.dev:443`)
`TIPOFF_AGENT_ADAPTERS_DIR`	`adapters`	Directory of `*.yaml` adapter files
`TIPOFF_AGENT_HTTP_ADDR`	`:8080`	Listen address for the agent’s webhook HTTP server

Action signing

Action payloads include a state object that round-trips through the iOS device (notification → device → action callback). Signing prevents tampering with this metadata in transit.

TIPOFF_AGENT_SIGNING_KEY=your-hmac-secret \
TIPOFF_AGENT_SIGNING_KEY_PREVIOUS=old-hmac-secret \
./tipoff-agent

Variable	Default	Description
`TIPOFF_AGENT_SIGNING_KEY`	(empty)	HMAC-SHA256 key for signing action payloads. If empty, signing is disabled.
`TIPOFF_AGENT_SIGNING_KEY_PREVIOUS`	(empty)	Previous key for rotation grace period

How it works: At notification time, the agent signs each action’s state object. The signature is embedded in the notification metadata and travels to the device and back. When an action event arrives, the signature is verified before the action is executed.

Key rotation: Set the new key as SIGNING_KEY and the old key as SIGNING_KEY_PREVIOUS. The agent tries the current key first, then falls back to the previous key. Once all in-flight notifications (signed with the old key) have been actioned or expired, remove SIGNING_KEY_PREVIOUS.

Operational

Variable	Default	Description
`TIPOFF_AGENT_ERROR_TARGET`	(empty)	Fallback TipOff user ID for error notifications when no adapter-level error handler matches
`TIPOFF_AGENT_CATALOG_REFRESH`	`5m`	How often to re-fetch the action catalog from the server. Set to `0` to disable.
`TIPOFF_AGENT_LOG_REQUESTS`	`on_error`	When to include full request detail (headers + body) in logs. Values: `always`, `on_filter`, `on_error`, `never`. Per-adapter `webhook.log_requests` overrides this. See request logging.

Security

Variable	Default	Description
`TIPOFF_EXPR_TIMEOUT`	`500ms`	Per-expression evaluation timeout
`TIPOFF_ADAPTER_MAX_SIZE`	`256KB`	Maximum adapter YAML file size before parsing
`TIPOFF_ENV_EXPAND_PREFIXES`	`TIPOFF_`	Comma-separated env var prefixes allowed in adapter YAML expansion
`TIPOFF_AGENT_LOG_BODIES`	`false`	Include request bodies in agent webhook logs
`TIPOFF_AGENT_FETCH_TIMEOUT`	`10s`	HTTP client timeout for adapter fetch requests
`TIPOFF_AGENT_ACTION_TIMEOUT`	`30s`	HTTP client timeout for adapter action requests
`TIPOFF_SSRF_ALLOW_CIDRS`	(empty)	Comma-separated CIDR ranges exempt from SSRF protection (e.g. `10.43.0.0/16` for cluster-internal services)

Complete agent example

A production agent deployment for Donetick and Vikunja adapters:

TIPOFF_AGENT_API_KEY=sk_abc123... \
TIPOFF_AGENT_GRPC_URL=grpc.tipoff.dev:443 \
TIPOFF_AGENT_ADAPTERS_DIR=/etc/tipoff/adapters \
TIPOFF_AGENT_HTTP_ADDR=:8080 \
TIPOFF_AGENT_SIGNING_KEY=hmac-secret-here \
TIPOFF_AGENT_ERROR_TARGET=user_abc \
TIPOFF_AGENT_CATALOG_REFRESH=5m \
TIPOFF_LOG_LEVEL=info \
TIPOFF_LOG_FORMAT=json \
DONETICK_URL=https://donetick.local \
DONETICK_API_KEY=dt_key_here \
DONETICK_WEBHOOK_SECRET=webhook-secret-here \
VIKUNJA_URL=https://vikunja.local \
VIKUNJA_TOKEN=vikunja-api-token \
VIKUNJA_WEBHOOK_SECRET=vikunja-webhook-secret \
./tipoff-agent

Server (operator)

These variables configure the hosted server. Most integrators don’t need these — they’re documented for operators and contributors.

Core

Variable	Default	Description
`TIPOFF_PORT`	`8080`	HTTP API port
`TIPOFF_GRPC_PORT`	`9091`	gRPC agent streaming port
`TIPOFF_METRICS_PORT`	`9090`	Prometheus metrics port
`TIPOFF_DB_PATH`	`tipoff.db`	SQLite database path
`TIPOFF_REDIS_URL`	(empty)	Redis URL; if empty, uses in-memory queue
`TIPOFF_LOG_LEVEL`	`info`	`debug` `info` `warn` `error`
`TIPOFF_LOG_FORMAT`	`json`	`json` or `text`

APNs

Variable	Default	Description
`TIPOFF_APNS_KEY_ID`		APNs auth key ID
`TIPOFF_APNS_TEAM_ID`		Apple Developer team ID
`TIPOFF_APNS_KEY_PATH`		Path to .p8 key file
`TIPOFF_APNS_BUNDLE_ID`		App bundle identifier
`TIPOFF_APNS_ENVIRONMENT`	`production`	`production` or `sandbox`

Auth / sessions

Variable	Default	Description
`TIPOFF_RESEND_API_KEY`	(empty)	Resend API key for magic link emails
`TIPOFF_RESEND_FROM`	`TipOff <noreply@tipoff.dev>`	From address for magic link emails
`TIPOFF_AUTH_BASE_URL`	`https://api.tipoff.dev`	Base URL for magic link callback
`TIPOFF_CORS_ORIGINS`	(empty)	Comma-separated allowed CORS origins
`TIPOFF_SESSION_TTL`	`720h`	Session lifetime (30 days)
`TIPOFF_MAGIC_LINK_TTL`	`15m`	Magic link token lifetime
`TIPOFF_COOKIE_DOMAIN`	`.tipoff.dev`	Domain attribute for session cookies

Security

Variable	Default	Description
`TIPOFF_MAX_REQUEST_BODY`	`2MB`	Maximum HTTP request body size
`TIPOFF_GRPC_MAX_MSG_SIZE`	`4MB`	Maximum gRPC message size
`TIPOFF_ALLOW_HTTP_WEBHOOKS`	`false`	Allow `http://` webhook URLs (default: require `https://`)
`TIPOFF_ALLOW_PLAINTEXT_REDIS`	`false`	Allow `redis://` instead of `rediss://` (TLS)
`TIPOFF_DB_ENCRYPTION_KEY`	(empty)	32-byte AES-256 key for encrypting webhook secrets at rest
`TIPOFF_WEBHOOK_MAX_RETRIES`	`3`	Maximum webhook delivery retries before dropping

Lifecycle

Variable	Default	Description
`TIPOFF_NOTIFICATION_TTL`	`168h`	How long un-actioned notifications live (7 days)
`TIPOFF_CLEANUP_INTERVAL`	`5m`	How often the TTL cleanup runs
`TIPOFF_RATELIMIT_ENABLED`	`true`	Rate limiting kill switch