Configuration · Kanesh

Kanesh is configured with environment variables. Every variable is optional: leave it out and the default applies. The full file with every variable is on Environment file.

How settings are read

Docker: pass variables with -e NAME=value or an env_file in Compose.
Go process: export them in your shell first. Kanesh does not load .env files by itself.
Studio: many security, access and email settings can also be changed in Settings. A variable that is set wins and shows as read-only in Studio. Leave it unset to manage it from Studio.

Server and data

Variable	Default	What it does
`HOST`	`127.0.0.1`	Address to listen on. Use `0.0.0.0` inside a container.
`PORT`	`8080`	Port for Studio and the API.
`DATA_DIR`	`.data` (`/data` in the image)	Folder for the SQLite file, uploads and the claim token. Back it up.
`SHUTDOWN_TIMEOUT`	`10s`	How long running requests may finish before shutdown, `1s` to `5m`.

Logging

Logs go to stderr. They never include request bodies, query values, passwords or record data.

Variable	Default	What it does
`LOG_LEVEL`	`info`	`debug`, `info`, `warn` or `error`.
`LOG_FORMAT`	`json`	`json` for log tools, `text` for reading in a terminal.
`LOG_SLOW_REQUEST`	`1s`	Requests at least this slow log as a warning. `0` turns it off.

Database

Variable	Default	What it does
`DATABASE_DRIVER`	`sqlite`	`sqlite`, `postgres` or `mysql`.
`DATABASE_URL`	unset	Connection for PostgreSQL (a URL) or MySQL (a go-sql-driver DSN, not `mysql://`).
`SQLITE_PATH`	`DATA_DIR/kanesh.db`	Custom path for the SQLite file.

If an external database fails, Kanesh stops. It never falls back to SQLite. See Database setup.

First owner

A new install is claimed once by its owner. These variables create or secure that owner.

Variable	Default	What it does
`BOOTSTRAP_TOKEN`	unset	Your own claim secret, 32 to 256 characters. Without it, a one-time token is written to `DATA_DIR/claim-token`.
`ADMIN_EMAIL`	unset	Creates the owner on a new install only.
`ADMIN_PASSWORD`	unset	Password for that owner. A restart never resets it.
`ADMIN_PASSWORD_FILE`	unset	Reads the password from a file, such as a mounted secret. Safer than `ADMIN_PASSWORD`.
`DEMO_MODE`	`false`	Shows the owner email and password on the login screen. Public demos only.

Note: The owner can do everything, like a super admin. Use DEMO_MODE=true only on a separate, throwaway install with sample data. Never in production.

Agents and tokens

Variable	Default	What it does
`MCP_ENABLED`	`false`	`true` turns on the read-only MCP endpoint for agents. See MCP for agents.
`AUTH_TOKEN_HEADER`	unset	Extra header for raw tokens, such as `X-Api-Key`. `Authorization: Bearer` always works.

Troubleshooting

.env has no effect when running Go: export the variables before starting the process.
A setting is read-only in Studio: the matching variable is set. Remove it to manage the setting in Studio.
Startup fails after a change: an invalid value stops startup on purpose. Check it against Environment file.