Configuration
Every setting can be given as a flag or as an environment variable. Precedence
is flags > environment > built-in default, and each flag mirrors one
MONOKI_* variable exactly. The source of truth is
internal/config/config.go.
| Flag | Environment variable | Default | What it does |
|---|---|---|---|
--state-dir |
MONOKI_STATE_DIR |
/var/lib/monoki |
Directory holding monoki.db. |
--addr |
MONOKI_ADDR |
:8080 |
Listen address. |
--allow-private-fetch |
MONOKI_ALLOW_PRIVATE_FETCH |
true |
Whether metadata lookups may reach private/LAN addresses. |
--fetch-timeout |
MONOKI_FETCH_TIMEOUT |
10 |
Seconds to spend on one lookup. |
--max-icon-bytes |
MONOKI_MAX_ICON_BYTES |
262144 |
Largest icon that will be stored. |
--dev |
MONOKI_DEV |
false |
Don't serve the embedded UI (use npm run dev). |
| — | LOG_LEVEL |
info |
debug, info, warn or error. |
An empty environment value counts as unset, so a stray MONOKI_ADDR= line in
an EnvironmentFile falls back to the default rather than producing an empty
listen address.
MONOKI_ALLOW_PRIVATE_FETCH
This one deserves its own explanation, because it defaults to true and that
inverts the usual advice about server-side fetching.
monoki exists to bookmark the apps you host, and those live at
http://nas.lan:5000 and http://192.168.1.10:8123. A server that refuses to
resolve private addresses cannot read the title or icon of the very apps this
product is for — and the failure looks like a bug rather than a policy.
What makes that acceptable:
- There is no open sign-up. Reaching the fetcher at all requires an account an admin deliberately created.
- The response surface is a page title and an image, not arbitrary content.
- Every other control still applies regardless of this flag: redirect caps, layered timeouts, response size limits, and a content-type allowlist checked against the actual bytes.
Set it to false if your instance has users you would not trust with a
curl on the server:
MONOKI_ALLOW_PRIVATE_FETCH=false monoki run
With it off, monoki refuses loopback, RFC1918, link-local (including the cloud
metadata address 169.254.169.254), CGNAT, multicast and several reserved
ranges. A refused lookup is not an error — the add form still works, and says
the address was blocked.
Example .env
MONOKI_STATE_DIR=/var/lib/monoki
MONOKI_ADDR=127.0.0.1:8080
MONOKI_ALLOW_PRIVATE_FETCH=true
MONOKI_FETCH_TIMEOUT=10
MONOKI_MAX_ICON_BYTES=262144
LOG_LEVEL=info