Configuration

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: control-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.

Field	Type	Notes
`cname_domain`	string	Base domain for custom domain CNAME targets. Required.
`database`	string	Single read-write MySQL DSN. Required.
`vault`	object	Vault connection settings. Required.
`restate`	object	Restate admin URL and worker HTTP port. Required.

Optional settings

Field	Type	Default	Notes
`instance_id`	string	-	Instance identifier for logs and tracing.
`region`	string	-	Region label for logs and tracing.
`observability`	object	-	Observability config (logging, metrics, tracing).
`default_domain`	string	`unkey.app`	Fallback domain for system operations, including wildcard certificate bootstrapping.
`build_platform`	string	`linux/amd64`	Build platform, format `linux/{arch}`.
`acme`	object	-	ACME config for cert issuance.
`depot`	object	-	Depot.dev config for builds.
`registry`	object	-	Registry credentials for builds.
`clickhouse`	object	-	ClickHouse connection settings.
`github`	object	-	GitHub App config for deploys.
`heartbeat`	object	-	Checkly heartbeat URLs.
`slack`	object	-	Slack webhook config for quota alerts.

ACME configuration

ACME settings live under acme. Enable Route53 DNS-01 challenges with acme.route53.

Field	Type	Default	Notes
`acme.enabled`	boolean	`false`	Enables ACME certificate issuance.
`acme.email_domain`	string	`unkey.com`	Used for ACME account email.
`acme.route53.enabled`	boolean	`false`	Enables Route53 DNS-01.
`acme.route53.access_key_id`	string	-	Required when Route53 is enabled.
`acme.route53.secret_access_key`	string	-	Required when Route53 is enabled.
`acme.route53.region`	string	`us-east-1`	Route53 region.
`acme.route53.hosted_zone_id`	string	-	Optional override for zone discovery.

Restate configuration

Field	Type	Default	Notes
`restate.admin_url`	string	`http://restate:9070`	Admin API endpoint.
`restate.api_key`	string	-	Optional Restate admin auth key.
`restate.http_port`	int	`9080`	Worker Restate ingress port.
`restate.register_as`	string	-	Optional self-registration URL.

Build and registry configuration

build.backend selects how builds run. The default depot backend runs builds on Depot.dev and is what production uses. Builds are enabled when registry.password is set. In that case, registry.repository, registry.username, build.depot.api_url, and build.depot.project_region must also be set. The kubernetes backend runs each build as a one-off BuildKit Job in the cluster the worker runs in. It needs no Depot account, but the build pods run privileged without further isolation, so it is intended for local development only. It requires registry.repository and in-cluster credentials with permission to manage Jobs and read Pods in the configured namespace. The worker accepts the legacy top-level [depot] table during migration. New configurations should use [build.depot].

Field	Type	Default	Notes
`build.backend`	string	`depot`	`depot` or `kubernetes`.
`build.depot.api_url`	string	-	Depot API endpoint.
`build.depot.project_region`	string	`us-east-1`	Depot storage region.
`build.kubernetes.namespace`	string	`unkey`	Namespace for build Jobs.
`build.kubernetes.image`	string	`moby/buildkit:v0.26.3`	BuildKit daemon image.
`registry.repository`	string	-	Registry repository path, for example `registry.depot.dev/abc123`.
`registry.username`	string	-	Registry username.
`registry.password`	string	-	Registry password or token.
`registry.insecure`	boolean	`false`	Allow plain-HTTP pushes. Local registries only.

ClickHouse configuration

Field	Type	Notes
`clickhouse.url`	string	ClickHouse connection string.
`clickhouse.admin_url`	string	Enables ClickHouse user service when set.

GitHub configuration

GitHub configuration is optional and can be omitted for local development.

Field	Type	Notes
`github.app_id`	int	GitHub App ID.
`github.private_key_pem`	string	GitHub App private key.
`github.allow_unauthenticated_deployments`	boolean	Only set true for local development.

Heartbeat and Slack

Field	Type	Notes
`heartbeat.cert_renewal_url`	string	Checkly heartbeat for cert renewals.
`heartbeat.quota_check_url`	string	Checkly heartbeat for quota checks.
`heartbeat.key_refill_url`	string	Checkly heartbeat for key refills.
`slack.quota_check_webhook_url`	string	Slack webhook for quota alerts.

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"
cname_domain = "${UNKEY_CNAME_DOMAIN}"
database = "${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}"

[build]
backend = "depot"

[build.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}"

Overview

Services

RFCs

Configuration model

Required settings

Optional settings

ACME configuration

Restate configuration

Build and registry configuration

ClickHouse configuration

GitHub configuration

Heartbeat and Slack

Example

​Configuration model

​Required settings

​Optional settings

​ACME configuration

​Restate configuration

​Build and registry configuration

​ClickHouse configuration

​GitHub configuration

​Heartbeat and Slack

​Example

Configuration model

Required settings

Optional settings

ACME configuration

Restate configuration

Build and registry configuration

ClickHouse configuration

GitHub configuration

Heartbeat and Slack

Example