Installation and security
Run the image
docker run -d --name desk \
-p 127.0.0.1:8080:8080 \
-p 127.0.0.1:5900:5900 \
-e AUTH_TOKEN=change-me \
-v "$PWD/userdata:/userdata" \
-v "$PWD/recordings:/recordings" \
psyb0t/auto-linux-desk:latest
Images are published for linux/amd64 and linux/arm64.
| Port | Serves |
|---|---|
| 8080 | HTTP API (POST /, screenshots, state, events, health) and MCP at /mcp/ |
| 5900 | noVNC in a browser (http://host:5900/), proxied to x11vnc |
Security
The API can run any command in the container. run_command runs any command it is given through bash -c, and launch_app starts any program, both as the desktop user. Without AUTH_TOKEN, anyone who can reach port 8080 can do both. The container prints a warning at startup when they are enabled and no token is set.
- Set
AUTH_TOKENbefore the API port is reachable from anywhere but loopback. Every endpoint except/healththen needsAuthorization: Bearer <token>, MCP included. A token in the query string is refused. - Set
DESK_EXEC_ENABLED=falsewhen clients only need input, windows, screenshots and the clipboard.run_commandandlaunch_appthen fail with an error. Input can still type into a terminal window that is already open, so this switch narrows the API, it is not a sandbox. - noVNC has no password. Publish port 5900 on loopback, or put it behind something that authenticates.
- The desktop user is not root and has no sudo. The container is the isolation boundary: do not mount the Docker socket or host directories you would not hand to the client.
Environment variables
| Variable | Default | Effect |
|---|---|---|
AUTH_TOKEN | unset | Bearer token for every endpoint except /health. Empty or whitespace counts as unset. |
DESK_EXEC_ENABLED | true | false refuses run_command and launch_app. Accepts true, 1, yes, on and false, 0, no, off; anything else stops startup. |
XVFB_RESOLUTION | 1920x1080 | Screen size as WIDTHxHEIGHT. |
XVFB_DEPTH | 24 | Screen colour depth. |
TZ | UTC | Time zone. |
PUID, PGID | 1000 | UID and GID the desktop runs as. PGID defaults to PUID. |
VNC_SHOW_CURSOR | true | true draws the pointer into the VNC view, false hides it. Any other value stops startup. |
HTTP_LISTEN_HOST, HTTP_LISTEN_PORT | 0.0.0.0, 8080 | API listen address inside the container. |
VNC_LISTEN_HOST, VNC_LISTEN_PORT | 0.0.0.0, 5900 | noVNC listen address inside the container. |
LOG_LEVEL | INFO | DEBUG, INFO, WARNING or ERROR, for the JSON logs on stderr. |
LOG_FILE | unset | Also write logs to this file, rotated at 10 MiB with 5 old files kept. |
DESK_LAUNCH_LOG_DIR | /tmp/auto-linux-desk/launched | Where launch_app writes each program’s output. |
AUTO_LINUX_DESK_PLUGINS | unset | Comma-separated Python modules to load as plugins. |
DESK_HOME, DESK_WRITABLE_DIRS, DESK_BANNER | /home/desk, /userdata /recordings, AUTO-LINUX-DESK | Set by derived images; see plugins and derived images. |
Users and volumes
The desktop runs as desk (UID and GID 1000, home /home/desk). The entrypoint starts as root, gives /userdata, /recordings and the home directory to PUID and PGID when anything in them belongs to someone else, runs the hooks, then drops to that UID and GID. Started with docker run --user, it skips the ownership fixes and the hooks and runs as the given user.
| Path | Holds |
|---|---|
/userdata | Free for your files; persisted when mounted. |
/recordings | MP4 files from stop_recording. Must stay writable for recording. |
/home/desk | Home directory, including the Openbox config. |
Entrypoint hooks
Before dropping privileges, the entrypoint sources every *.sh file in /etc/auto-linux-desk/entrypoint.d/ in filename order, as root. They do not run under docker run --user. Hooks can read TARGET_UID, TARGET_GID and DESK_HOME. Use them for setup that needs root, such as fixing ownership of an extra directory.