Configuration reference
Kuvasz can be configured in two ways: via a YAML configuration file, or via environment variables. Most of the configuration options are available in both formats, but some are only available in one of them.
Info
The YAML configuration file should be mounted as a volume in the Docker container under /config/kuvasz.yml.
If you modify your configuration (via YAML or ENV, it doesn't matter), you need to restart the Kuvasz container for the changes to take effect. In certain cases if you changed an environment variable, you might need to rebuild the container as well.
Authentication
Toggling authentication
2.0.0
true
boolean
If it's set to false, the authentication will be completely disabled, and you can access the web UI or the API without any credentials.
Disabling authentication
If you disable authentication, anyone can access your Kuvasz instance (assuming that it's exposed), so make sure to secure it by other means, like a firewall or a reverse proxy with authentication.
If you're running it locally, or on your private network, it might be fine, but be aware of the risks.
Authentication max age
2.0.0
86400
number
The maximum age of the authentication token in seconds, default is 24 hours (86400 seconds). After this time, the admin user will need to log in again on the web UI.
JWT signing secret
a random value generated on each startup
string
The secret used to sign the JWT that backs the web UI session. By default Kuvasz generates a new random secret on every startup, which makes the sessions don't survive a restart - every logged in user has to log in again after Kuvasz is restarted.
If you want sessions to survive restarts, you can set a fixed one, but only via YAML.
Keep it secret, keep it strong
Anyone who knows this secret can forge valid sessions. Use a long, random value (at least 32 characters / 256 bits is required), keep it out of version control, and rotate it if you suspect it leaked (rotating invalidates all existing sessions, forcing a re-login).
Credentials
When are the admin credentials required?
The admin username and password are only used by the built-in username/password login form. They are required when authentication is enabled and OIDC is not configured. When OIDC is enabled, the form-based login is disabled, so you don't need to set ADMIN_USER / ADMIN_PASSWORD at all.
Admin username
auth enabled & OIDC not configured
string
The username for the admin user.
Admin password
auth enabled & OIDC not configured
string
The password for the admin user, minimum 12 characters long, can't be the same as the username.
API key
2.0.0
string
The API key for the REST API. It's optional: if you don't set it (or leave it blank), API key-based authentication is simply disabled, and the REST API can only be accessed when authenticated through the web UI / OIDC login. When it's set, it must be at least 16 characters long, otherwise the application won't start.
Note
This key grants access to the REST API only. The MCP server is protected by a separate MCP API key.
MCP API key
4.0.0
string
The API key dedicated to the MCP server (the /mcp endpoint). It's optional: if you don't set it (or leave it blank), the MCP endpoint cannot be accessed via API key authentication at all. When it's set, it must be at least 16 characters long, otherwise the application won't start.
This key is separate from the REST API key on purpose: the /mcp endpoint can only be accessed with this key, and the REST API key (or a web UI / OIDC session) does not grant access to it. This lets you hand out MCP access independently from REST API access, and revoke either one without affecting the other.
OIDC authentication (optional)
As an alternative to the built-in username/password form, you can configure an OpenID Connect (OIDC) provider. When OIDC is enabled, the login page will display a "Login (OIDC)" button instead of the username/password form, and the username/password form-based login will be disabled. The API key authentication continues to work regardless.
Tip
Once OIDC is enabled, the Settings page (and the /settings endpoint of the REST API) shows the effective OIDC configuration — the issuer, client ID, the exact redirect (callback) URL, the valid post logout redirect URI, and the web origin to register with your provider. The client secret is never exposed.
When OIDC is enabled, the ADMIN_USER and ADMIN_PASSWORD properties are no longer needed (and are ignored), since the built-in username/password login is disabled. If you still want API key-based programmatic access to the REST API, configure ADMIN_API_KEY — it works independently of the chosen interactive login method.
Enable OIDC
4.0.0
false
boolean
When OIDC is enabled, you must also provide the issuer, client ID, and client secret below, otherwise the application won't start.
OIDC issuer
4.0.0
OIDC enabled
string
The issuer URL of your OIDC provider. Kuvasz uses it to discover the provider's endpoints via its /.well-known/openid-configuration document.
OIDC client ID
4.0.0
OIDC enabled
string
OIDC client secret
4.0.0
OIDC enabled
string
OIDC authorization server
4.0.0
auto-detected from the issuer URL
string
Identifies the type of your OIDC provider. For most cloud providers Kuvasz infers this automatically from the issuer URL, but in general it's recommended to explicitly provide it.
The value is case-insensitive, and the supported providers are:
| Value | Provider |
|---|---|
AUTH0 |
Auth0 |
COGNITO |
AWS Cognito |
KEYCLOAK |
Keycloak |
MICROSOFT |
Microsoft (Entra ID) |
OKTA |
Okta |
ORACLE_CLOUD |
Oracle Cloud (IDCS) |
OIDC end-session
4.0.0
true
boolean
When OIDC is enabled, signing out from the web UI also logs you out at the OIDC provider. This behavior is enabled by default whenever OIDC is on. If you want to opt out and only clear the local Kuvasz session on logout, disable the end-session support:
Register the post-logout redirect URI
Most providers require the post-logout redirect URI to be explicitly registered on the client. For example, in Keycloak add https://<your-kuvasz-host>/* (or the exact https://<your-kuvasz-host>/auth/logout URL) to the client's Valid post logout redirect URIs. Otherwise the provider will reject the redirect back to Kuvasz after logout.
OIDC email allowlist
4.0.0
empty (every authenticated user is allowed)
string
By default any user your OIDC provider successfully authenticates is allowed to sign in and is granted full access. If your provider serves a broader audience than the people who should access Kuvasz (e.g. a shared corporate IdP or a public provider), restrict access with an allowlist of email addresses:
Restrict access when no allowlist is configured
Without an email allowlist, every user the OIDC provider can authenticate gets full access to Kuvasz — including the REST API. If your provider is shared with other applications, backed by a public sign-up, or otherwise authenticates more people than should be able to administer Kuvasz, this effectively hands them admin rights.
If you choose not to configure an allowlist, it's strongly recommended to use a dedicated, restricted OAuth client instead — one that only the intended users can obtain tokens for (for example, by limiting the client to a specific group/role assignment in your provider). Otherwise, configure the allowlist below.
When set, only users whose email matches one of the listed addresses are allowed in; everyone else is rejected at login. Matching is case-insensitive and surrounding whitespace is ignored. Provide the list as a comma-separated value when using the environment variable.
Note
The allowlist relies on the email claim, so make sure your provider returns it (it's part of the standard email scope, which Kuvasz requests by default).
Require verified email
4.0.0
true
boolean
When the allowlist is in use, an email is only accepted if the provider also reports it as verified (the email_verified claim). This prevents a user with an unverified — and potentially spoofed — email from satisfying the allowlist. If your provider doesn't supply email_verified (or you intentionally want to skip the check), disable it:
This setting only has an effect when the email allowlist is configured.
Database
Kuvasz uses a PostgreSQL database to store its data. You can use an existing PostgreSQL instance, and point Kuvasz to a separate database in it, the only thing you should watch out for is that the database user has the necessary permissions to create schemas and tables.
The database connection can be configured only via environment variables.
Info
The minimum, tested version of PostgreSQL is 14, alpine distributions are supported.
Host
A hostname or IP address of the database server.
Port
Database name
The name of the database to connect to. Kuvasz will create a schema called kuvasz in the database, and will use it to store all the data it needs.
User
The username to connect to the database. The user must have the necessary permissions to create schemas and tables.
Password
The password of the user above.
SMTP
Tip
Using an SMTP server is optional, it's only needed if you want to use the email integration to send notifications about events.
The SMTP configuration can be set only via YAML.
Be aware that if you include smtp-config in your configuration, then you'll need to provide all the required properties of it, otherwise Kuvasz won't start.
Host
2.0.0
smtp-config is present
string
The hostname or IP address of the SMTP server you want to use for sending emails.
Port
2.0.0
smtp-config is present
number
The port of the SMTP server you want to use for sending emails.
Username
2.0.0
null
string
The username to authenticate with the SMTP server. If your SMTP server doesn't require authentication, you can omit specifying this property, or set it explicitly to null.
Password
2.0.0
null
string
The password to authenticate with the SMTP server. If your SMTP server doesn't require authentication, you can omit specifying this property, or set it explicitly to null.
Transport strategy
2.0.0
SMTP_TLS
enum: SMTP_TLS, SMTPS, SMTP
The transport strategy to use for sending emails. The default is SMTP_TLS, which uses TLS encryption for the connection. You can also use SMTPS (implicit SSL) or SMTP (no encryption).
Miscellaneous
Timezone
The timezone to use for the application. It's recommended to set it to your local timezone.
Event data retention
2.0.0
365
number
The number of days to keep the finished events in the database. After this time, finished uptime & SSL events will be cleaned up to spare space in the database. The minimum is 1 day.
Latency data retention
2.0.0
7
number
The number of days to keep the latency data in the database. After this time, latency data will be cleaned up to spare space in the database. The minimum is 1 day.
Event logging
Toggles the log based event handler, which writes the uptime & SSL events coming from monitors (i.e. UP/DOWN/redirect/etc.) to the STDOUT of the container.
Examples:
✅ Your monitor "test_up" (https://test.com) is UP (200). Latency was: 1826ms.🚨 Your monitor "test_down" (https://test2.com) is DOWN. Reason: Connect Error: Connection refused: test2.comℹ Request to "test_redirected" (https://redirected.com) has been redirected🔒️ Your site "test_good_ssl" (https://good-ssl.com) has a VALID certificate🚨 Your site "test_bad_ssl" (https://no-subject.badssl.com/) has an INVALID certificate. Reason: PKIX path validation failed
Language
2.0.0
en
string
The language to use. If you would like to translate Kuvasz to your desired language, check out the Localization section for more details.
Currently supported languages
- English (
en) - French (
fr) - Polish (
pl)
MCP server
4.0.0
false
boolean
Enables the built-in MCP server, which exposes your monitors, incidents, configuration, etc. as tools that AI assistants can call. The server is available at /mcp once enabled and is protected by a dedicated MCP API key, separate from the REST API key.
Check for updates
3.0.1
true
boolean
Toggles the automatic check for new versions of Kuvasz. If it's enabled, the application will check for new releases in the background, and if a new version is available, it will show a notification on the UI and populate the relevant information through the API too.
HTTP check timeout
3.4.0
30
number
The global read timeout limit for HTTP monitors (the default and the maximum value are both 30 seconds). Useful if you would like to use a relatively low response time threshold or uptime check interval on your monitors, and you want to make sure that consecutive checks don't wait for slow responses. For example, if you use a low uptime check interval on all of your monitors (like 10 seconds), then it makes sense to also set a global timeout lower than the default, otherwise the checks won't really happen every 10 seconds because the HTTP client will wait more than that until it eventually fails.
Full configuration example
You can find the full configuration example below, which includes all the options currently available. You can use it as a starting point for your own configuration.
micronaut:
security:
enabled: true
token:
generator.access-token.expiration: 86400 # 24 hours
jwt.signatures.secret.generator.secret: your-very-long-random-secret
oauth2:
clients:
oidc:
client-id: your-client-id
client-secret: your-client-secret
authorization-server: keycloak
openid:
issuer: https://your-oidc-provider/
end-session.enabled: true
mcp.server.enabled: false
metrics:
enabled: true
export:
otlp:
enabled: true
url: https://example.host:4318/v1/metrics
headers: 'Authorization=Bearer Your-collectors-API-token,key2=value'
step: PT1M
prometheus:
enabled: true
descriptions: true
---
metrics-exports:
http-uptime-status: true
http-latest-latency: true
ssl-status: true
ssl-expiry: true
push-uptime-status: true
icmp-uptime-status: true
icmp-latest-latency: true
icmp-latest-packet-loss: true
---
admin-auth:
username: YourSuperSecretUsername
password: YourSuperSecretPassword
api-key: ThisShouldBeVeryVerySecureToo
mcp-api-key: ThisShouldBeVeryVerySecureToo
oidc:
allowed-emails:
- alice@example.com
- bob@example.com
require-verified-email: true
---
app-config:
event-data-retention-days: 365
latency-data-retention-days: 7
log-event-handler: true
language: en
check-updates: true
http-check-timeout-seconds: 30
---
smtp-config:
host: 'your.smtp.server'
port: 465
transport-strategy: SMTP_TLS
username: YourSMTPUsername
password: YourSMTPPassword
ENABLE_AUTH=true
AUTH_MAX_AGE=86400 # 24 hours
ADMIN_USER=YourSuperSecretUsername
ADMIN_PASSWORD=YourSuperSecretPassword
ADMIN_API_KEY=ThisShouldBeVeryVerySecureToo
ADMIN_MCP_API_KEY=ThisShouldBeVeryVerySecureToo
ENABLE_OIDC=true
OIDC_ISSUER=https://your-oidc-provider/
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_AUTH_SERVER=keycloak
ENABLE_OIDC_END_SESSION=true
OIDC_ALLOWED_EMAILS=alice@example.com,bob@example.com
OIDC_REQUIRE_VERIFIED_EMAIL=true
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=postgres
DATABASE_USER=change_me
DATABASE_PASSWORD=change_me
EVENT_DATA_RETENTION_DAYS=365
LATENCY_DATA_RETENTION_DAYS=7
ENABLE_LOG_EVENT_HANDLER=true
APP_LANGUAGE=en
ENABLE_CHECK_UPDATES=true
HTTP_CHECK_TIMEOUT_SECONDS=30
ENABLE_MCP_SERVER=false
TZ=UTC
ENABLE_METRICS_EXPORT=true
ENABLE_OTLP_EXPORT=true
OTLP_EXPORT_URL=https://example.host:4318/v1/metrics
OTLP_EXPORT_HEADERS='Authorization=Bearer Your-collectors-API-token,key2=value'
OTLP_EXPORT_STEP=PT1M
ENABLE_PROMETHEUS_EXPORT=true
ENABLE_PROMETHEUS_DESCRIPTIONS=true
# Enable the individual metrics
ENABLE_HTTP_UPTIME_STATUS_EXPORT=true
ENABLE_HTTP_LATEST_LATENCY_EXPORT=true
ENABLE_SSL_STATUS_EXPORT=true
ENABLE_SSL_EXPIRY_EXPORT=true
ENABLE_PUSH_UPTIME_STATUS_EXPORT=true
ENABLE_ICMP_UPTIME_STATUS_EXPORT=true
ENABLE_ICMP_LATEST_LATENCY_EXPORT=true
ENABLE_ICMP_LATEST_PACKET_LOSS_EXPORT=true