API and development

UI password#

Off by default: on a trusted home network the web UI is open. Enable it from Settings -> Authentication, or by hashing a password on the command line and pasting the result into the config:

# on the host:
./monloader -hash-password 'your-password'
# or via Docker:
docker exec -it monloader monloader -hash-password 'your-password'

Put the output in auth.password_hash and set auth.enable_password = true. When enabled, the web UI is gated by a session cookie (lifetime auth.session_lifetime_days, default 7); removing the password clears every session.

API tokens and scopes#

monloader’s JSON API lives under /api/v1/ and requires a bearer token; the API is disabled until at least one token exists. Create tokens in Settings -> Authentication: each is named, individually revocable, and its secret is shown once at creation, never again.

Each token’s config dialog sets its scopes: read (list the queue, inspect jobs, list sites) and/or write (enqueue URLs, manage jobs). A call whose token lacks the needed scope gets 403 insufficient_scope. Tokens provisioned by pairing have fixed scopes and are removed by removing the pairing.

/health, /api/v1/openapi.json, and /api/v1/docs stay open without a token.

curl -H "Authorization: Bearer <token>" \
     -X POST http://localhost:8456/api/v1/queue \
     -d '{"url":"https://danbooru.donmai.us/posts/xxx"}'

API reference#

The API documents itself in-app:

• HTML reference: /api/v1/docs (linked in the footer).
• OpenAPI spec: /api/v1/openapi.json.

Error codes#

A failed queue item carries one of these stable codes; scripts and the monsender extension can branch on them:

The job’s summary aggregates its items: { created, duplicate, enriched, matched, replaced, skipped, archived, failed, canceled, total }. archived is the part of skipped that gallery-dl’s download archive passed over, which is what the queue row’s force download re-fetches. The outcomes themselves are described in downloading.

Building from source#

monloader is pure Go with no CGO, so the binary is static and builds without system libraries:

make build      # go build with the version injected from VERSION.md
# or directly:
go build -o monloader ./cmd/monloader

./monloader -config /path/to/monloader.toml

make build injects the version and repository URL via -ldflags (read from VERSION.md and REPOSITORY.md), which feed the footer and /health; a plain go build reports dev.

CLI flags and subcommands:

• -config - path to the TOML config file (default ./monloader.toml).
• -hash-password '...' - print a bcrypt hash for the UI password and exit.
• -desktop - the desktop profile: OS-native paths, a log file, a browser at startup, the first-run setup. The desktop downloads have it baked in; -desktop=false turns one back into a server build.
• -no-browser - with -desktop, do not open a browser at startup.
• -version - print the version and exit.
• healthcheck - probe the local /health endpoint and exit non-zero if it is not healthy (accepts -config and -timeout).

gallery-dl#

The container image bundles Python and a pinned gallery-dl. Outside the container you supply it yourself; if it is not on PATH, set gallerydl.binary_path to its location. A missing binary is not fatal at startup - the UI and API still run, the bundled version shows as unavailable, and downloads fail until it is installed.

Adding a site profile#

Mappings are data, not code, so tracking gallery-dl’s growing site list is a data change. There are three levels:

• No profile needed. Any gallery-dl site without a profile uses the generic fallback (sites), and the [[tag_overrides]] / [[rating_overrides]] tables in monloader.toml (mapping) can correct a generic site with no release.
• Your own profile. The settings profile tab (mapping) writes /config/profiles/<category>.json, applied immediately and layered over the shipped set. You can also write the file by hand; a file that fails to parse or validate is skipped with a warning in the log.
• A shipped profile. The built-ins are the same files, embedded from internal/mapping/profiles/<category>.json. Contributing one is a pull request that adds your /config/profiles/<category>.json.

A profile’s fields: