Configuration Reference

Table of contents

• Global Settings
  • include_apps
  • data_home
• Server Settings
  • server.bind
  • server.bind_systemd
  • server.tls_key
  • server.tls_cert
  • server.worker_threads
  • server.max_connections
  • server.mdns
  • server.mdns_hostname
  • server.mdns_instance_name
• Configured Applications
  • apps.<app name>.description
  • apps.<app name>.command
  • apps.<app name>.environment
  • apps.<app name>.app_path
  • apps.<app name>.header_image
  • apps.<app name>.xwayland
  • apps.<app name>.force_1x_scale
  • apps.<app name>.isolate_home
  • apps.<app name>.shared_home_name
  • apps.<app name>.tmp_home
• Default App Settings
  • default_app_settings.xwayland
  • default_app_settings.force_1x_scale
  • default_app_settings.isolate_home
  • default_app_settings.tmp_home

Global Settings

include_apps

# Example (default unset)
include_apps = ["/etc/magic-mirror/apps.d"]

If set, this special setting instructs the server to load additional application configurations from the given files or directories. Each file (or file in in the directories) should be named using the scheme <NAME>.toml or <NAME>.json, where <NAME> is the name of the application, following the rules outlined below. The contents should be identical to the configuration for an individual app.

data_home

# Example (default unset)
data_home = "/var/lib/magic-mirror"

This determines where the server stores application data, i.e. the $HOME for containerized applications. If not set, then $XDG_DATA_HOME/mmserver is used, or $HOME/.local/share/mmserver if $XDG_DATA_HOME is not set.

If you're running magic-mirror as a permanent daemon, you should set this to something like /var/lib/magic-mirror.

Server Settings

This section contains configuration options for the network server.

server.bind

# Default
bind = "localhost:9599"

Where the server should listen for incoming connections. IPv6 addresses are supported. Use 0.0.0.0 or [::] to listen on all available interfaces.

server.bind_systemd

# Default
bind_systemd = false

If set, bind will be ignored, and the server will instead listen for incoming connections on the socket specified by the LISTEN_FDS environment variable. See the systemd documentation on "socket activation", here: https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html

server.tls_key

# Example (default unset)
tls_key = "/path/to/tls.key"

Used for TLS. Both are required unless the host portion of the bind address resolves to a private address (as defined by RFCs 1918, 4193, and 6598) or otherwise not routable, for example 127.0.0.1, 192.168.24.25, or fd12:3456:789a:1::1.

server.tls_cert

# Example (default unset)
tls_cert = "/path/to/tls.cert"

server.worker_threads

# Default
worker_threads = 8

The number of threads to spawn for handling incoming requests.

server.max_connections

# Default
max_connections = 4

The maximum number of concurrent connections the server will accept. Use inf to specify no limit.

server.mdns

# Default
mdns = true

Whether to use mDNS to allow clients to discover the server.

server.mdns_hostname

# Example (default unset)
mdns_hostname = "mycomputer.local."

The hostname to advertise over mDNS. Defaults to "$(uname -n).local. if left unset, or ignored if mdns is false.

server.mdns_instance_name

# Example (default unset)
mdns_instance_name = "MYCOMPUTER"

The instance name to advertise over mDNS. Defaults to the unqualified value of mdns_hostname, converted to uppercase.

Configured Applications

Each application you want to stream must be configured in advance, with each application as its own section. Applications can, alternatively, be configured as individual files. See the documentation for include_apps above for more information. At least one application must always be configured.

App names must be unique and only contain characters in the set [a-z0-9-_]. The section is structured as a dictionary, with the key as the application name.

An example application configuration follows. (Note that unlike the rest of this file, this application is not included in the default configuration.)

apps.<app name>.description

# Example (default unset)
description = "Steam"

A short name for the app.

apps.<app name>.command

# Example (default unset)
command = ["steam", "-gamepadui"]

The command to run. Must be in $PATH or absolute.

apps.<app name>.environment

# Example (default unset)
environment = { "FOO" = "bar" }

Key/value pairs to set in the environment when running the command.

apps.<app name>.app_path

# Example (default unset)
app_path = "My Games/Puzzle Games"

Configure a "path" for the application. Clients can use this to group apps into folders. This has nothing to do with the local filesystem. Paths should use unix path separators. They may include characters in the set [A-Za-z0-9-_ ] (including spaces).

apps.<app name>.header_image

# Example (default unset)
header_image = "/path/to/image.png"

Add a header image to the app, for displaying in clients. The image must be a PNG file and less than 1mb. Any aspect ratio is permitted, but roughly 2:1 with a transparent background will work best.

apps.<app name>.xwayland

# Example (default unset)
xwayland = true

Enable XWayland support for this application. This is required for any applications that are built for the legacy X11 windowing system, such as Steam.

If unset, defaults to default_app_settings.xwayland.

apps.<app name>.force_1x_scale

# Example (default unset)
force_1x_scale = false

Force the app to run at 1x. This is useful for applications where you know in advance they don't support any UI scaling, for example any application run through XWayland. This setting will ensure that the app always renders at the full session resolution, but may result in small font sizes or other UI elements.

If unset, defaults to default_app_settings.force_1x_scale.

apps.<app name>.isolate_home

# Example (default unset)
isolate_home = true

Isolate the home directory. If set, the application will see a clean, sandboxed $HOME (and /home/$(whoami)), rather than the system-wide one. This home directory is saved between runs of the app to <data_home>/homes/<shared_home_name>.

If unset, defaults to default_app_settings.isolate_home.

apps.<app name>.shared_home_name

# Example (default unset)
shared_home_name = same as application name

If isolate_home is set to true, this sets a name for the home directory, can be shared between apps. For example, multiple apps with this option set to 'myhome' will all see the same $HOME when they run. By default, this is set to the name of the application.

If unset, defaults to default_app_settings.shared_home_name.

apps.<app name>.tmp_home

# Example (default unset)
tmp_home = false

If isolate_home is set to true, this mounts a brand new $HOME (using tmpfs) each time the application is run. If set, shared_home_name is ignored.

Note that any data saved while the app is running will be irrevocably destroyed when it exits.

If unset, defaults to default_app_settings.tmp_home.

Default App Settings

This section can be used to set global defaults for all apps. Any setting here can be overriden in the configuration for each individual app.

default_app_settings.xwayland

# Default
xwayland = true

default_app_settings.force_1x_scale

# Default
force_1x_scale = false

default_app_settings.isolate_home

# Default
isolate_home = true

default_app_settings.tmp_home

# Default
tmp_home = false