Skip to main content

Documentation Index

Fetch the complete documentation index at: https://engineering.unkey.com/llms.txt

Use this file to discover all available pages before exploring further.

Unkey services read configuration from a TOML file passed at startup. Environment variables can be referenced with ${VAR} and are expanded before parsing. Defaults and validation run after parsing. The config schema maps to svc/ctrl/worker/config.go. The control plane worker is configured via a TOML file: unkey run ctrl worker --config=unkey.toml.

​
Configuration model

The control plane worker loads configuration from a TOML file using config.Load. Defaults and validation are applied after parsing. Runtime-only values (for example Clock) cannot be set in the file.

​
Required settings

These fields must be set for production deployments.
FieldTypeNotes
cname_domainstringBase domain for custom domain CNAME targets. Required.
databaseobjectMySQL connection settings. Required.
vaultobjectVault connection settings. Required.
restateobjectRestate admin URL and worker HTTP port. Required.

​
Optional settings

FieldTypeDefaultNotes
instance_idstring-Instance identifier for logs and tracing.
regionstring-Region label for logs and tracing.
observabilityobject-Observability config (logging, metrics, tracing).
default_domainstringunkey.appUsed for sentinel bootstrapping.
build_platformstringlinux/amd64Build platform, format linux/{arch}.
sentinel_imagestringghcr.io/unkeyed/unkey:localSentinel image override.
acmeobject-ACME config for cert issuance.
depotobject-Depot.dev config for builds.
registryobject-Registry credentials for builds.
clickhouseobject-ClickHouse connection settings.
githubobject-GitHub App config for deploys.
heartbeatobject-Checkly heartbeat URLs.
slackobject-Slack webhook config for quota alerts.

​
ACME configuration

ACME settings live under acme. Enable Route53 DNS-01 challenges with acme.route53.
FieldTypeDefaultNotes
acme.enabledbooleanfalseEnables ACME certificate issuance.
acme.email_domainstringunkey.comUsed for ACME account email.
acme.route53.enabledbooleanfalseEnables Route53 DNS-01.
acme.route53.access_key_idstring-Required when Route53 is enabled.
acme.route53.secret_access_keystring-Required when Route53 is enabled.
acme.route53.regionstringus-east-1Route53 region.
acme.route53.hosted_zone_idstring-Optional override for zone discovery.

​
Restate configuration

FieldTypeDefaultNotes
restate.admin_urlstringhttp://restate:9070Admin API endpoint.
restate.api_keystring-Optional Restate admin auth key.
restate.http_portint9080Worker Restate ingress port.
restate.register_asstring-Optional self-registration URL.

​
Build and registry configuration

Builds are enabled when registry.password is set. In that case, registry.url, registry.username, depot.api_url, and depot.project_region must be set.
FieldTypeDefaultNotes
depot.api_urlstring-Depot API endpoint.
depot.project_regionstringus-east-1Depot storage region.
registry.urlstring-Registry endpoint URL.
registry.usernamestring-Registry username.
registry.passwordstring-Registry password or token.

​
ClickHouse configuration

FieldTypeNotes
clickhouse.urlstringClickHouse connection string.
clickhouse.admin_urlstringEnables ClickHouse user service when set.

​
GitHub configuration

GitHub configuration is optional and can be omitted for local development.
FieldTypeNotes
github.app_idintGitHub App ID.
github.private_key_pemstringGitHub App private key.
github.allow_unauthenticated_deploymentsbooleanOnly set true for local development.

​
Heartbeat and Slack

FieldTypeNotes
heartbeat.cert_renewal_urlstringCheckly heartbeat for cert renewals.
heartbeat.quota_check_urlstringCheckly heartbeat for quota checks.
heartbeat.key_refill_urlstringCheckly heartbeat for key refills.
slack.quota_check_webhook_urlstringSlack webhook for quota alerts.
slack.sentinel_rollout_webhook_urlstringSlack webhook used by SentinelRolloutService to post rollout progress.

​
Example

[observability.tracing]
sample_rate = 0.1

[observability.logging]
sample_rate = 0.01
slow_threshold = "2s"

[observability.metrics]
prometheus_port = 9090

region = "${UNKEY_REGION}"
instance_id = "${POD_NAME}"
default_domain = "${UNKEY_DEFAULT_DOMAIN}"
build_platform = "linux/amd64"
sentinel_image = "ghcr.io/unkeyed/unkey:v2.0.77"
cname_domain = "${UNKEY_CNAME_DOMAIN}"

[database]
primary = "${UNKEY_DATABASE_PRIMARY}"

[vault]
url = "${UNKEY_VAULT_URL}"
token = "${UNKEY_VAULT_TOKEN}"

[acme]
enabled = true
email_domain = "unkey.com"

[acme.route53]
enabled = true
access_key_id = "${UNKEY_ACME_ROUTE53_ACCESS_KEY_ID}"
secret_access_key = "${UNKEY_ACME_ROUTE53_SECRET_ACCESS_KEY}"
region = "${UNKEY_ACME_ROUTE53_REGION}"

[restate]
admin_url = "${UNKEY_RESTATE_ADMIN_URL}"
http_port = 9080
register_as = "${UNKEY_RESTATE_REGISTER_AS}"

[depot]
api_url = "https://api.depot.dev"
project_region = "us-east-1"

[registry]
repository = "${UNKEY_REGISTRY_REPOSITORY}"
username = "${UNKEY_REGISTRY_USERNAME}"
password = "${UNKEY_REGISTRY_PASSWORD}"

[clickhouse]
url = "${UNKEY_CLICKHOUSE_URL}"
admin_url = "${UNKEY_CLICKHOUSE_ADMIN_URL}"

[github]
app_id = ${UNKEY_GITHUB_APP_ID}
private_key_pem = "${UNKEY_GITHUB_PRIVATE_KEY_PEM}"

[heartbeat]
cert_renewal_url = "${UNKEY_CERT_RENEWAL_HEARTBEAT_URL}"
quota_check_url = "${UNKEY_QUOTA_CHECK_HEARTBEAT_URL}"
key_refill_url = "${UNKEY_KEY_REFILL_HEARTBEAT_URL}"

[slack]
quota_check_webhook_url = "${UNKEY_QUOTA_CHECK_SLACK_WEBHOOK_URL}"
sentinel_rollout_webhook_url = "${UNKEY_SENTINEL_ROLLOUT_SLACK_WEBHOOK_URL}"