Configuration Reference

Configuration reference

Environment variables

Set these in .env beside the controller's compose file. Keelarr rewrites this file when you change a path in the app, preserving anything it does not manage.

Variable	Default	What it does
KEELARR_PORT	4687	Host port the controller is published on
KEELARR_VERSION	latest	Image tag to run. Pin this to hold a version
KEELARR_LOG_LEVEL	info	debug, info, warn, error
KEELARR_DATA_DIR	../data	Where settings, credentials, jobs and logs live
HOST_STACK_ROOT	$HOME/keelarr/stacks	Generated compose files per service
HOST_CONFIG_ROOT	$HOME/keelarr/config	Each app's config directory
HOST_MEDIA_ROOT	$HOME/keelarr/media	Your library
HOST_DOWNLOADS_ROOT	$HOME/keelarr/media/downloads	Download client output
HOST_PLEX_LOGS_ROOT	$HOME/keelarr/plex-logs	Optional, Tautulli only. Mounted read-only
KEELARR_DEMO	unset	1 runs demo mode against a simulated stack, with no auth

The HOST_* roots are mounted at the same absolute path inside the container. See First Run and Host Setup for why.

Settings

Held in settings.json in the data directory, and edited through the app rather than by hand.

Setting	Default	Notes
adapterType	detected	qnap or generic-docker
dockerBin	docker	Path to the Docker binary if it is not on PATH
stackRoot	per adapter	Must be visible to the controller
configRoot	per adapter
mediaRoot	per adapter
downloadsRoot	per adapter
plexLogsRoot	empty	Optional
hostUrl	http://localhost	Used to build the links you click through to
puid / pgid	1000	Passed to the LinuxServer images
timezone	host
selectedServiceIds	eight defaults	Which apps are managed
serviceOverrides	none	Per-service port, image, containerName and more

Overriding one service

To change a single app's port or image, use its entry in Settings. This writes a serviceOverrides entry, which survives removal so a reinstall brings the service back as itself.

Data directory

File	Holds
settings.json	Everything above
auth.json	The password hash and session secret. Mode 0600
jobs.json	Job history, so a restart does not lose what happened
updates.json	Last update check per service
activity.json	The activity feed
keelarr.log	Rotates at 5MB, two files kept

No database. Back up this directory and you have backed up Keelarr's state — the stacks themselves are in the stack root.

Generated files, per service

In <stackRoot>/<service>/:

File	Purpose
compose.yml	An ordinary Compose project you can run by hand
.env	Its resolved values
.env.example	Key names only, documenting what is expected without repeating this host's paths

These are yours. Read them, edit them, commit them.

API

All routes are under /api and require a session except /api/health.

State and health

Method	Route
GET	/api/health — public; the container healthcheck uses this
GET	/api/state — everything the dashboard renders
GET	/api/auth/status
POST	/api/auth/setup, /api/auth/login, /api/auth/logout

Host

Method	Route
GET	/api/host/browse — directory picker
GET/POST	/api/host/detect
POST	/api/settings

Services

Method	Route
POST	/api/services/:id/install, /generate, /restart
POST	/api/services/:id/check-update, /upgrade, /rollback
POST	/api/services/check-all, /api/services/upgrade-all
GET	/api/services/:id/removal-preview
POST	/api/services/:id/remove

Adoption

Method	Route
GET	/api/import/scan, /api/import/:containerId/preview
POST	/api/import/:containerId/adopt-draft, /cutover
POST	/api/services/:id/revert-cutover

Wiring and jobs

Method	Route
GET	/api/wiring/check — read-only
POST	/api/wiring/apply
GET	/api/jobs, /api/jobs/:jobId

Long operations return 202 with a job. Poll /api/jobs/:jobId for its steps.