Skip to content
kōan
Contents

Start

Server

Library

Playback

Automation

Reference

Protocol

Running a server

koan --headless runs kōan with no terminal UI, serving the library to other machines: a web UI, the Subsonic API, GraphQL and MCP, all on one port. The container image runs the same thing; see In a container.

Quick start

koan auth setup                       # signing keys and the first admin account
koan subsonic setup                   # turn on the Subsonic API
export KOAN_SERVER__URL=https://music.example.com
koan --headless --bind 0.0.0.0        # serve on every interface, port 4000

The server refuses to start without server.url, the one address clients reach it at. It cannot tell which of the addresses it answers on another device can reach, and every link it hands out is built on this one: invites, share links, MCP's sign-in, the Last.fm callback. A server used only at home can give its LAN address, such as http://192.168.1.20:4000. Signed-in apps learn it from the server and know the server by it, so a phone that reaches it by its domain and a laptop that reaches it by its LAN address still recognise each other as on the same server.

Server flags

Flag Effect
--headless No TUI, API only
--playground Enable GraphiQL web IDE at GET /graphql
--subsonic PORT Also serve the Subsonic API on a port of its own, for clients that expect one
--port PORT Custom GraphQL port (default: 4000)
--bind ADDR Bind address (default: 127.0.0.1)
-d, --daemonize Detach and run in the background, logging to ~/.config/koan/koan.log. Implies --headless
--api Serve the API alongside the TUI. Implied by --port, --bind, --subsonic and --playground
--no-api Do not serve the API alongside the TUI, even with [graphql] enabled = true

MCP is served at /mcp on the same port, with its own OAuth sign-in on server.url; see MCP Integration.

The TUI serves no API unless one of the flags above or [graphql] enabled = true asks it to. When it does, the setup page stays closed, so the first admin comes from koan auth setup.

A headless server indexes the library folders when it starts and again whenever they change, as the desktop app does.

Configuration

# config.local.toml — where this machine is reached
[server]
url = "https://music.example.com"

[graphql]
port = 4000               # the server's port
bind = "127.0.0.1"        # bind address
playground = false        # GraphiQL IDE

# config.local.toml — which machine serves Subsonic
[subsonic]
enabled = true            # serve /rest/* on the main port
port = 4040               # and on a port of its own (optional)

# config.toml — waking iPhones through kōan's push relay
[push]
enabled = true            # false keeps the server off the relay

Or via environment variables:

export KOAN_SERVER__URL=https://music.example.com
export KOAN_GRAPHQL__PORT=8080
export KOAN_GRAPHQL__BIND=0.0.0.0
export KOAN_GRAPHQL__PLAYGROUND=true
export KOAN_PUSH__ENABLED=true    # false keeps the server off the push relay

Under a path

kōan can share a host with other services at a path such as https://host.example/koan, which is how Tailscale Funnel puts several services on one name and port. Give server.url the path:

[server]
url = "https://host.example/koan"

The server takes the path off each request before routing it, so a proxy may forward /koan/rest/ping as it is or strip it to /rest/ping (Funnel's --set-path strips it); both reach the same place. Redirects and cookies are given the path back, and the web UI and share pages link relative to it. Apps, the TUI and Subsonic clients are given the whole address, path included.

The path may use letters, digits, /, -, ., _ and ~, and may not begin with a segment kōan routes itself (/rest, /ui, /library, /share and the like), which a stripping proxy would make ambiguous; the server refuses to start with one.

The web UI then works only through that address: a browser that reaches the server directly, on its LAN address, is sent to /koan/…, which the server does not prefix for itself. Apps and Subsonic clients work on either.

An MCP client looks for the OAuth server's metadata between the host and the path, at https://host.example/.well-known/oauth-authorization-server/koan, which is outside what the proxy forwards for /koan. Forward that path to the same path on kōan, which answers it. With Funnel, as a second mount:

tailscale funnel --bg --set-path /koan http://127.0.0.1:4000
tailscale funnel --bg --set-path /.well-known/oauth-authorization-server/koan \
  http://127.0.0.1:4000/.well-known/oauth-authorization-server/koan

Remote TUI

Control a running headless kōan from a TUI on another machine. The server plays the audio; the TUI is a remote control:

koan play --server http://host:4000

It follows the server's nowPlaying and queueUpdated subscriptions over /graphql/ws, so it hears of a change when it happens and sends nothing while nothing changes. A command the server refuses, and losing or regaining the server, show on the status line.

To play its library on the machine you are sitting at, sign in to it as a remote server instead (koan remote login, or Settings in the apps). Tracks then play through the local engine and download into the local cache like any other remote library.

Authentication

Auth is enabled by default. See Authentication for the full guide.

The first account

A new server has no accounts, and nothing can sign in until one exists. Until then the web UI answers with a setup page instead of sign-in: open the server in a browser, choose the admin's username and password, and you are signed in as that admin. The page closes for good once any account exists, however it was made.

Whoever reaches the setup page first becomes the admin, and the server logs a warning while it is open. On a server reachable from the internet, make the account as soon as it starts, or turn the page off and make the admin from a shell instead:

[graphql]
setup_wizard = false          # or KOAN_GRAPHQL__SETUP_WIZARD=false

With the page off, or for scripts, the first admin is made with koan auth setup, run on the server itself, against the same config directory the server uses. The server can be running at the time; it picks the account up on the next sign-in.

Where the server runs Run
Directly on a machine koan auth setup
docker run docker exec -it koan koan auth setup
Docker Compose docker compose exec koan koan auth setup
Kubernetes kubectl -n koan exec -it deploy/koan -- koan auth setup

It asks for a username and offers to generate a password, which it prints once. To run it without a terminal, from a script or a CI job, pass both in the environment:

docker exec -e KOAN_USERNAME=admin -e KOAN_PASSWORD='…' koan koan auth setup

Once there is an admin, everything else is done signed in: the web UI's Users page, the apps' Settings, or GraphQL create accounts and send invites, so nobody else needs a shell. koan auth setup does nothing on a server that already has accounts; koan auth create-user adds one from the shell, and koan auth reset-password recovers an admin who is locked out.

The API binds to 127.0.0.1 by default. If you expose it on 0.0.0.0 with --bind 0.0.0.0, make sure auth is enabled (it is by default) or restrict access at the network level.

Cookie auth needs cookie_secure = false over plain HTTP, and browser clients need their origin listed in cors_origins. If you reach the server through a hostname, add it to allowed_hosts — anything else is refused. See Configuration.

To disable auth (localhost-only setups):

[graphql]
auth_enabled = false

With auth disabled, anything that can reach the port is an admin; see Recovery / lockout before doing it.

Web UI

The server answers http://host:4000/ with a browser UI: the library, search, a play queue, playlists and share links, laid out for a phone as well as a desktop. Playback happens in the browser, streaming from the server; the server's own player is not involved. Media keys, headphone buttons and the system's now-playing controls drive it. Covers are resized once and kept in covers/ in the config directory, which is held to 4 GB by removing the covers read least recently; deleting it only costs regenerating them.

On a phone, Playlists, Tracks, Recently played, Favourites and History sit under a Library tab, since the tab bar has room for six.

Track menu and properties

A track row's menu (right-click, press and hold on a phone, or its ⋯) offers play next, queue, favourite, share, and the album and artist.

Properties shows what the server knows about the track, for working out why a record appears twice or the wrong file plays: each of its sources (the file, and an entry from a remote server it syncs) with their tags and format, its uid and its album's, and its MusicBrainz ids. Admin accounts also see the file's full path on the server, with a copy button. Other accounts are not shown paths, since they describe the server's filesystem.

Rescan

Admin accounts find Rescan at the foot of the Library page, which the sidebar links for them on a wide screen as well as the phone's tab bar. It looks through the library folders for files added, changed or removed since the last scan, which the folder watcher normally does by itself. It is the same job as triggerScan, so a scan started from either shows in both.

Read every file again ignores the scan cache and reads every file's tags. An upgrade that reads more from tags needs this, since the files themselves did not change (triggerScan(reread: true)).

The section also shows the scans the server runs by itself, with what started each, how many of the files it has to read (new and changed ones, or every file on a re-read) it has read so far, and how it ended. A bar fills as it reads; while the scan is still finding out how many files that is, it shows a still band. The start-up scan after an upgrade that empties the scan cache reads every file and can take a long while.

Caches

Below Rescan, admin accounts see what the server keeps beside the library, so slow covers can be diagnosed without reading its logs: the cover cache's size against its 4 GB budget, how many covers it holds at each size and how many records it remembers as having no art, what the background warm is doing (making covers, idle, or paused because the cache is full) with how far it has got and when it runs next, and what the last sweep removed. A server syncing from another also shows its download cache, and every server its track, record and artist counts and how long the last scan took. The section updates as the warm, a sweep or a scan moves.

Warm now makes covers for the records still without them instead of waiting for the next pass, and Clear covers removes every kept cover, misses included, after saying how many and how much space that is. The same figures and actions are in GraphQL as serverCaches, warmCovers and clearCoverCache.

Signing in

Sign in with a kōan account (koan auth create-user). The session is the same pair of HttpOnly cookies the JSON login sets, so behind plain HTTP the UI needs cookie_secure = false, and a hostname it is reached by must be in allowed_hosts. The access cookie lasts access_token_ttl; an open page renews it from the refresh cookie, and a page loaded after it lapsed renews on the way in. With auth_enabled = false the UI is open to anyone who can reach the port.

Behind an authenticating proxy

When a proxy such as Authelia, Authentik or oauth2-proxy signs people in before they reach kōan, the web UI can take the account from the header the proxy sets instead of asking for a password:

[graphql]
proxy_auth_header = "Remote-User"
proxy_auth_from = ["172.18.0.5"]     # the proxy's own address

The header is believed only on a connection whose address is in proxy_auth_from, which names the proxy itself, not the clients behind it, and only when it carries a single value.

The account must already exist in kōan with exactly that name, byte for byte and case included: a name the server has no account for is refused, not created. A header from the proxy that names no one account (sent twice, merged, or not UTF-8) is refused too, and signs the browser out rather than leaving it on the session it had.

A session through the proxy is an access cookie alone, with no refresh cookie, and each page load and each renewal derives it again from the header. It therefore lasts no longer than the proxy's say-so: a browser whose proxy sign-in changes to another account is handed over on its next page load, and once the proxy stops naming an account (sign-out, or removal at the identity provider), what kōan issued for it lapses within access_token_ttl.

Signing out is done at the proxy. A password sign-in made without the proxy, such as koan auth login, keeps its refresh token as usual.

Turning proxy mode on does not end sessions signed in with a password before it: their refresh tokens still rotate at /auth/refresh. To end them, have each person sign out of the web UI once, or reset the account's password (koan auth reset-password, or Users in the web UI), which also revokes its API keys and app passwords and so signs its apps out too.

Proxy sign-in is on only when both settings are set. The server refuses to start, naming the problem, when one is set without the other, when the header is not a header name or an entry is neither an address nor a range, and when an entry covers every address (0.0.0.0/0, ::/0). When it is on, the server logs the header and the addresses it believes it from.

Name the proxy's own address rather than its network where you can. Anything else that connects from inside proxy_auth_from can name any account. Under Docker that includes the network's gateway (172.18.0.1 on 172.18.0.0/16), through which connections to a published port can arrive: from the host itself through docker-proxy, and from every client under rootless Docker or Docker Desktop. Do not publish kōan's port when it sits behind the proxy, and give the proxy a fixed address on the network (ipv4_address in Compose).

kōan reads the header only on web UI pages and the MCP consent page (/oauth/authorize), which the proxy must cover. Subsonic clients, kōan's apps and MCP clients cannot pass through an interactive proxy sign-in, so the proxy must let these through without its sign-in, and no others (each under the server's path, if it has one):

Path Used by
/rest Subsonic clients and kōan's apps, including the koanLink WebSocket
/graphql GraphQL clients
/mcp MCP clients
/auth/login, /auth/refresh, /auth/logout koan auth login and other token clients
/oauth/register, /oauth/token MCP clients signing in
/.well-known MCP clients discovering the OAuth server
/share Public share links, for people without an account

Exempt these exact paths, never whole /auth or /oauth prefixes. On a path the proxy does not cover it sets no header of its own, so whatever a client sent passes through from the proxy's address. Have the proxy remove the header from every incoming request before it authenticates, so a mistaken exemption carries no header at all. With Caddy:

music.example.com {
    request_header -Remote-User

    @public path /rest/* /graphql /graphql/* /mcp /mcp/* /auth/login /auth/refresh /auth/logout /oauth/register /oauth/token /.well-known/* /share/*
    handle @public {
        reverse_proxy koan:4000
    }
    handle {
        forward_auth authelia:9091 {
            uri /api/authz/forward-auth
            copy_headers Remote-User
        }
        reverse_proxy koan:4000
    }
}

With Traefik, a headers middleware that clears the header, placed before the forward-auth middleware on every router to kōan:

http:
  middlewares:
    strip-remote-user:
      headers:
        customRequestHeaders:
          Remote-User: ""

Subsonic clients

Besides playing, browsing and favourites, Subsonic clients get:

Sign-in, and which credential each kind of client should use, is in Authentication.

Scrobbling

Each account can forward its plays to ListenBrainz, from the web UI's Scrobbling page (linked from Account), Settings → Integrations → Scrobbling in the Mac, iOS and Android apps, or the terminal UI's Settings, and to Last.fm, through the web UI's page, which the terminal UI's Settings also opens (see Last.fm). For ListenBrainz, paste the user token from its settings and the server checks it, then sends the plays already in the account's history and, from then on, every play kōan's apps and other Subsonic clients report (scrobble), with now-playing notices. It is the server that sends, so no client needs configuring, and a play reported once is forwarded once whichever device made it.

Plays wait in the database until ListenBrainz accepts them, so a restart or an outage delays them rather than losing them; the page shows how many are waiting. A token ListenBrainz stops accepting is shown there, and plays are kept until the account connects again. Plays the server's own player records are forwarded in the history sent on connecting, when they were listened to for half the track or four minutes, but not as they happen. Tracks without an artist or title are not sent.

Last.fm

Last.fm needs an API key and shared secret for the server, which its admin registers at https://www.last.fm/api/account/create and sets as lastfm.api_key and lastfm.secret in config.local.toml (see Configuration), and server.url, so that Last.fm can send people back.

The Scrobbling page then offers Connect Last.fm: it sends the person to Last.fm to approve kōan and back, and the server exchanges what Last.fm returns for a session key it keeps, never showing it.

The return address carries a one-time code made when the person left, so a link someone else makes cannot connect their Last.fm to your account. Without the key and secret the page says Last.fm is not set up.

Plays are sent as they are reported, fifty to a call, with now-playing notices, and wait in the database the same way. Last.fm ignores plays more than two weeks old, so connecting sends only the last two weeks of history, and a play still waiting past that is dropped rather than sent. A session key Last.fm stops accepting (the person revoked kōan there) is shown on the page, and plays are kept until the account connects again. Connecting Last.fm is done in the web UI; the apps show it in koanScrobbling as a service named lastfm and can disconnect it with service=lastfm.

For apps

The apps reach this through the koanScrobbling extension: koanScrobbling reports the account's connection (account name, plays waiting, and the error when the token was refused), koanScrobblingConnect takes a token in a form POST body, and only there, so that it stays out of access logs (one in the query string is ignored), and koanScrobblingDisconnect removes it (service=lastfm for Last.fm; ListenBrainz when none is named). The token is never sent back. The Apple TV app shows the connection but cannot change it, having no keyboard.

Sharing

A server makes share links itself: createShare (GraphQL, MCP, or a Subsonic client's own share button) returns <server.url>/share/<id>, a page anyone can open without an account, with a player for each shared track and a Download button that sends the shared files, untouched, as one zip. The server writes at most four zips at once and answers further downloads with 503 until one finishes; a download whose visitor stops reading for 30 seconds is ended.

A share is a slice of the library, shown the way the app shows it: one track shares its album cued to that track, an album the album, an artist their albums in release order, and several tracks stay a list. What a share covers is fixed when it is made; an artist share does not grow when the library does. Pages carry OpenGraph and Twitter card tags, with the cover as an absolute og:image on server.url, so a pasted link unfurls with its artwork.

The page and its audio answer for the share's own tracks and nothing else, addressed by position in the share rather than by library id. An expired, revoked or made-up id is the same 404. List shares with shares, set an expiry with updateShare, revoke with deleteShare. kōan's apps and terminal UI, signed in to this server, share through it.

Playing on a linked app

kōan's macOS, iOS, Android and Apple TV apps and the terminal UI, signed in to a kōan server, hold a WebSocket open to it at /rest/koanLink (authenticated like any other /rest call; a kōan extension, not part of OpenSubsonic). Down it the server sends commands; up it each app reports what it is playing, where it is in the track, and its queue.

{ clients { name platform playing nowPlaying positionMs queue { trackId title current } } }
mutation { playOnClient(trackIds: ["812", "813"]) { ok message } }
mutation { queueOnClientWhenAdded(artist: "Rilo Kiley", album: "Under the Blacklight") { id } }
Mutation Does
playOnClient(trackIds, startAt, enqueue) Replace the queue and play, or append with enqueue: true
playNextOnClient(trackIds) Insert after the current track
jumpOnClient(trackId) Play that track: from the queue, or slotted in after the current one
removeFromClient(trackIds), clearClient Edit the queue
controlClient(action), seekOnClient(positionMs) Pause, resume, next, previous; seek
setPlayModeOnClient(shuffle, repeat) Shuffle on or off; repeat OFF, QUEUE or ONE
setSleepTimerOnClient(minutes, endOf), cancelSleepTimerOnClient Fade out and pause after some minutes or at the end of the TRACK or RECORD, keeping the queue
handOffClient(to, from) Move one app's queue and playhead to another and pause the first
syncClient Pull what the server has added since the app last synced
syncClients(full) Have every device of the account sync, now if linked, else when it next links
evictOnClients(trackIds) Have every linked app delete its downloaded copies of those tracks, after a damaged file on the server is replaced
queueOnClientWhenAdded(artist, album, playNext) Queue an album once it is in the library, e.g. one slsk is downloading. Checked after every library scan; lapses after a day. clientOrders lists them, cancelClientOrder withdraws one

Every mutation that addresses one app, apart from handOffClient with its from and to, takes an optional client, an id or name from clients. Without it the server picks the app that is playing, else the one that played in the last six hours, else the only one linked, and otherwise answers with the choices so the caller can ask.

Track ids are the server's; an app that has not seen one syncs first, and its pages show what the sync brought in. Every account, admin included, sees and commands only its own apps, so a server shared by several people never sends one person's music to another's phone.

An app is linked while it runs. iOS suspends a backgrounded app that is not playing, and the server drops a link it has not heard from in 100 seconds. A server with [push] on, as it is by default, wakes a suspended phone through kōan's push relay to relink and take the command, choosing the one seen most recently when no client is named, since a reinstalled app leaves its old entry behind under the same name; a request to play arrives as a notification to tap, since iOS does not let an app start audio from the background. Opening the app relinks at once.

In a container

The image at ghcr.io/radiosilence/koan, for amd64 and arm64, runs koan --headless --bind 0.0.0.0, keeps config, database and auth keys in /config, and needs no sound card. latest and vX.Y.Z are releases; main and a commit sha follow the main branch between them.

Mount the library read-only, list it under [library] folders in /config/config.toml, and add the public hostname to allowed_hosts. Create the first admin on the setup page the web UI shows until one exists, or with koan auth setup inside the container (see The first account), and koan subsonic setup to enable the Subsonic API.

Set KOAN_SERVER__URL to the public address; the container does not start without it.

Kubernetes

The server needs one pod with two volumes: the library, read-only, and a state directory at /config that outlives the pod. It is a single SQLite index, so it runs as one replica, on one node. Set KOAN_LIBRARY__FOLDERS, KOAN_GRAPHQL__ALLOWED_HOSTS and KOAN_SERVER__URL as in the Compose example below, and terminate TLS in front of it.

With Pulumi

@radiosilence/koan-pulumi is a Pulumi component that deploys the server into a namespace. Its version is koan's: each release publishes both, and a pinned package deploys exactly that image.

It is published to GitHub Packages, which wants a token with read:packages even for public packages:

# .npmrc
@radiosilence:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
npm install @radiosilence/koan-pulumi @pulumi/kubernetes @pulumi/pulumi zod

createKoan(provider, namespace, config) validates config against KoanConfSchema and creates a Deployment, a Service on port 80 and a NetworkPolicy. It creates no Ingress; it returns routes naming the Service and hostname, for whatever fronts the cluster to route.

import * as k8s from "@pulumi/kubernetes";
import { createKoan } from "@radiosilence/koan-pulumi";

const provider = new k8s.Provider("cluster", {});
const ns = new k8s.core.v1.Namespace("koan", { metadata: { name: "koan" } }, { provider });

const koan = createKoan(provider, ns.metadata.name, {
  hostname: "music.example.com",
  library: { existingClaim: "music" },
  state: { existingClaim: "koan-state" },
  push: { enabled: true }, // false keeps the server off kōan's push relay
});

export const routes = koan.routes;
Option
hostname Required. Becomes allowed_hosts and server.url (https://<hostname>), so TLS is expected in front
library Required: existingClaim or hostPath. Mounted read-only at /music
state existingClaim or hostPath, mounted at /config. Unset, it is an emptyDir and the index and accounts go with the pod
image repository, tag (defaults to the package's version), pullPolicy
nodeSelector Needed with a hostPath, which is one node's disk
push enabled (default true): whether the server wakes the iOS app through kōan's push relay when it is suspended. Set enabled: false to keep the server off the relay
resources Requests default to 250m / 256Mi, limits to 6 CPU / 5Gi
networkPolicy On by default. Ingress only from api.from (a Traefik pod by default) plus extraIngress; egress to cluster DNS and the public internet, with privateCidrs excluded

With persistent state, each update first runs koan check-db in a Job against a snapshot of the live database. If the new version's migration fails there, the update stops and the old pod keeps serving. kubelet creates a missing hostPath as root, and koan runs as uid 1000, so an init container hands the state directory to that uid before the server starts; initPermissions.enabled: false turns it off. The root filesystem is read-only, and the artwork and lyrics caches live in an emptyDir, rebuilt after a restart.

Unknown options are rejected rather than ignored, so a stack carrying options a newer package removed fails at pulumi preview.

Two servers during an upgrade

Two koan processes can share one state directory on one node for the minutes an upgrade overlaps them: SQLite's WAL lets both read and write. The state directory must be on a local filesystem, which WAL needs anyway and the lock below relies on. Only one scans and watches the library, whichever holds watch.lock beside the database; the other serves and waits on the lock, taking over the moment the first exits, however it exits. A build older than the database refuses to start, naming the schema versions, rather than serving errors.

A release that changes the schema is covered too. The new server migrates on start in one transaction, so the old one, mid-request, sees the old schema or the new one and never a mixture, and a migration that fails leaves the database as it was. From the moment it commits, the old server refuses every database connection it is asked for, drains as it would on SIGTERM and exits, so it never writes the old shape into the new schema; what fails is the requests it had in flight at that moment. Devices linked to the outgoing server reconnect to the new one, as after any restart.

Once it is running, create the admin account in the pod:

kubectl -n koan exec -it deploy/koan -- koan auth setup

Docker Compose

kōan behind Caddy, which obtains and renews the TLS certificate. Save as compose.yaml:

services:
  koan:
    image: ghcr.io/radiosilence/koan:latest
    restart: unless-stopped
    environment:
      KOAN_LIBRARY__FOLDERS: '["/music"]'
      KOAN_GRAPHQL__ALLOWED_HOSTS: '["${KOAN_HOST:?set KOAN_HOST to the server hostname}"]'
      KOAN_GRAPHQL__COOKIE_SECURE: "true"
      KOAN_SERVER__URL: https://${KOAN_HOST}
      KOAN_SUBSONIC__ENABLED: "true"
      KOAN_PUSH__ENABLED: "true"   # "false" keeps the server off kōan's push relay
    volumes:
      # The image runs as uid 1000; a bind mount here has to be writable by it.
      - koan-config:/config
      - ${MUSIC:?set MUSIC to the music folder}:/music:ro

  caddy:
    image: caddy:2
    restart: unless-stopped
    ports: ["80:80", "443:443", "443:443/udp"]
    command: caddy reverse-proxy --from ${KOAN_HOST} --to koan:4000
    volumes:
      - caddy-data:/data

volumes:
  koan-config:
  caddy-data:

On a machine whose hostname resolves to it, with ports 80 and 443 open:

KOAN_HOST=music.example.com MUSIC=/mnt/music docker compose up -d
docker compose exec koan koan auth setup   # the admin account

Then open https://music.example.com and sign in. The Subsonic API is on for kōan accounts; koan subsonic setup adds a shared secret for clients that have none. Config, the database and keys live in the koan-config volume. The image runs as uid 1000, so a bind mount in its place has to be writable by that uid.