Configuration

Configuration

ankerctl is configured through environment variables (read at startup) and a JSON file managed by the config CLI subcommand. This page lists every supported variable, where each one is read, and what it does.

For Docker deployments, copy .env.example to .env and uncomment what you need — docker compose loads it automatically.

Configuration file

Platform	Path
Linux / macOS	~/.config/ankerctl/default.json
Windows	%APPDATA%\ankerctl\default.json
Docker	/home/ankerctl/.config/ankerctl/default.json (mounted from host)
HA add-on	/data/.config/ankerctl/default.json

The same directory holds:

• history.db — SQLite print history
• filament.db — SQLite filament profile store
• bed_leveling/ — saved 7×7 bed grids (when ANKERCTL_LOG_DIR is set)

Security default.json contains user_id, auth_token, and per-printer mqtt_key. Treat it like a password — never commit it, never paste it into issues.

Inspect the current config (with secrets redacted) via:

./ankerctl.py config show

Environment variables

Server

Variable	Default	Description
FLASK_HOST	127.0.0.1	IP address the web server binds to
FLASK_PORT	4470	Port the web server listens on
FLASK_SECRET_KEY	(auto-generated)	Session cookie secret. Set explicitly if you want sessions to survive a restart.
PRINTER_INDEX	0	Select a printer by index when multiple are configured. Setting this locks the active printer and disables the web UI selector (returns 403).
UPLOAD_MAX_MB	2048	Max upload file size in MB
UPLOAD_RATE_MBPS	10	Upload speed to printer in Mbit/s. Choices: 5, 10, 25, 50, 100. Overrides the per-printer config-file value.

Security and feature flags

Variable	Default	Description
ANKERCTL_API_KEY	(unset)	API key for write-operation auth. Takes precedence over the key stored in default.json. Unset = no auth.
ANKERCTL_DEV_MODE	false	Enable the Debug tab and /api/debug/* endpoints. Do not enable in production.
ANKERCTL_LOG_DIR	(unset)	Directory for log files; enables file logging when set. Default in CLI: /logs if /logs exists, otherwise None. Default for the debug API: /logs.
ANKERCTL_MQTT_CA_CERT	(unset)	Path to a custom CA certificate (PEM) for pinning a self-signed MQTT broker (e.g. local Mosquitto in offline mode). See also CLI flag --mqtt-ca-cert.

Apprise notifications

All variables below are optional. When APPRISE_ENABLED is false (default) the notification subsystem is fully disabled and no other variable matters.

Variable	Default	Description
APPRISE_ENABLED	false	Enable push notifications via Apprise
APPRISE_SERVER_URL	(unset)	Apprise API server URL (e.g. http://apprise:8000)
APPRISE_KEY	(unset)	Apprise notification key/ID
APPRISE_TAG	(unset)	Optional Apprise tag filter
APPRISE_EVENT_PRINT_STARTED	true	Notify when a print starts
APPRISE_EVENT_PRINT_FINISHED	true	Notify when a print finishes successfully
APPRISE_EVENT_PRINT_FAILED	true	Notify when a print fails or is cancelled
APPRISE_EVENT_GCODE_UPLOADED	true	Notify when a file finishes uploading
APPRISE_EVENT_PRINT_PROGRESS	true	Notify on progress thresholds
APPRISE_PROGRESS_INTERVAL	25	Progress notification interval (%)
APPRISE_PROGRESS_INCLUDE_IMAGE	false	Attach a camera snapshot to progress notifications
APPRISE_PROGRESS_MAX	0	Override the progress scale divisor (0 = auto-detect)
APPRISE_SNAPSHOT_QUALITY	hd	Snapshot quality: sd (848×480), hd (1280×720), fhd (1920×1080)
APPRISE_SNAPSHOT_FALLBACK	true	Fall back to the G-code preview image when live capture fails
APPRISE_SNAPSHOT_LIGHT	false	Turn on the printer light for the snapshot duration

See Notifications for setup walk-through and Apprise URL examples.

Print history

Variable	Default	Description
PRINT_HISTORY_RETENTION_DAYS	90	Days to keep history entries
PRINT_HISTORY_MAX_ENTRIES	500	Max history entries (oldest pruned first)

Timelapse

Variable	Default	Description
TIMELAPSE_ENABLED	false	Enable automatic timelapse capture (requires ffmpeg)
TIMELAPSE_INTERVAL_SEC	30	Seconds between snapshots
TIMELAPSE_MAX_VIDEOS	10	Max videos to keep
TIMELAPSE_SAVE_PERSISTENT	true	Save assembled videos persistently
TIMELAPSE_CAPTURES_DIR	/captures	Directory used for video storage
TIMELAPSE_LIGHT	(unset)	Light mode: snapshot (per-frame: on, wait 1.5s, shoot, wait 1s, off) or session (on at start, off at finish)
TIMELAPSE_CAMERA_SOURCE	follow	Source: follow (use Home page selection), printer (built-in cam), or external (configured external feed)

See Timelapse for behavior details.

Home Assistant MQTT Discovery

Variable	Default	Description
HA_MQTT_ENABLED	false	Enable HA MQTT Discovery integration
HA_MQTT_HOST	localhost	HA MQTT broker host
HA_MQTT_PORT	1883	HA MQTT broker port
HA_MQTT_USER	(unset)	MQTT broker username
HA_MQTT_PASSWORD	(unset)	MQTT broker password
HA_MQTT_DISCOVERY_PREFIX	homeassistant	HA discovery prefix
HA_MQTT_TOPIC_PREFIX	ankerctl	State / command topic prefix
HA_BASE_URL	http://homeassistant.local:8123	HA REST base URL for the MJPEG camera auto-registration
HA_TOKEN	(unset)	HA long-lived access token (Profile → Long-Lived Access Tokens)

See Home Assistant for entity list and Lovelace examples.

Authentication (API key)

ankerctl supports optional API key authentication. When no key is set the web server is open (default, backwards compatible). When a key is set:

• GET requests are unauthenticated by default (read-only). A small set of protected GET paths still require auth — see API Reference for the list.
• POST and DELETE requests always require auth.
• /ws/ctrl WebSocket has inline auth (the first message must include a valid key).
• Setup paths (/api/ankerctl/config/upload, /api/ankerctl/config/login) are exempt from auth when no printer is configured yet.
• All /api/debug/* paths require auth.

Three ways to authenticate:

Method	Use it for
X-Api-Key: <key> header	Slicers (PrusaSlicer, OrcaSlicer set this automatically when you fill the API Key field)
?apikey=<key> URL parameter	Browser bootstrap. After the first request a session cookie is set automatically.
Session cookie	Browser, persists for the duration of the cookie.

Setting the key

./ankerctl.py config set-password              # random key (printed once — save it!)
./ankerctl.py config set-password my-secret    # specific key
./ankerctl.py config remove-password           # disable auth

Or via env var:

ANKERCTL_API_KEY=my-secret-key

The env var takes precedence over the key in default.json.

Multi-printer setups

If your account has more than one AnkerMake M5, config import and config login add them all to default.json. The web UI shows a printer selector dropdown in the navbar. You can also pin a specific printer:

• Env var: PRINTER_INDEX=1 — locks the selection; the navbar dropdown becomes read-only and POST /api/printers/active returns 403.
• CLI flag: ./ankerctl.py -p 1 mqtt monitor — for a single command.

Switching the active printer in the UI restarts all services (MQTT, PPPP, video, HA, etc.). Switching is blocked during an active print (returns 409).

CLI global options

These flags work on every ankerctl.py subcommand:

Flag	Description
-p INDEX, --printer-index INDEX	Select printer by index (0-based)
-k, --insecure	Disable TLS verification (debugging only — never in production)
-v, --verbose / -q, --quiet	Increase / decrease log verbosity
--pppp-dump FILE	Capture all PPPP packets to FILE for later analysis
--mqtt-ca-cert FILE	Pin a custom CA cert for the MQTT broker (offline / self-hosted Mosquitto)