# Music Assistant Server Configuration Options: Complete Guide to Core Settings and Provider Setup

> Explore Music Assistant server configuration options with this comprehensive guide. Learn about core settings in config.yaml and provider setup for a seamless music experience.

- Repository: [Music Assistant/server](https://github.com/music-assistant/server)
- Tags: how-to-guide
- Published: 2026-06-15

---

**Music Assistant stores all settings as ConfigEntry objects, with core server options defined in [`config.yaml`](https://github.com/music-assistant/server/blob/main/config.yaml) and provider-specific settings exposed through `get_config_entries()` methods that can be accessed via `self.config.get_value()` in Python.**

The `music-assistant/server` repository manages configuration through a unified system where core HTTP server parameters, data directories, and TLS settings live alongside provider-specific authentication tokens and quality preferences. Configuration values are persisted in YAML format and accessed programmatically through the `mass.config` object or provider-local `self.config` instances. Understanding these configuration options enables precise control over network binding, music source authentication, and player behavior.

## Core Server Configuration Options

The foundational settings for Music Assistant are defined in [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py) and [`music_assistant/constants.py`](https://github.com/music-assistant/server/blob/main/music_assistant/constants.py), with HTTP server security handled in [`music_assistant/helpers/webserver.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/webserver.py). These values are stored in the [`config.yaml`](https://github.com/music-assistant/server/blob/main/config.yaml) file located in the data directory (default: `$HOME/.musicassistant`).

### Network and HTTP Settings

The server exposes several critical networking parameters that control how the web interface and API accept connections:

- **`host`** (string, default: `"0.0.0.0"`): Defines the network interface for the HTTP server listener. Set to `"127.0.0.1"` to restrict local access only.
- **`port`** (integer, default: `8095`): Specifies the TCP port for the HTTP API and web UI.
- **`allow_remote_access`** (boolean, default: `False`): When enabled, exposes the API to external networks, required for Home Assistant integration.
- **`http_password`** (secure string, optional): Enables basic authentication for the HTTP API when set.

### TLS and Security Configuration

For HTTPS deployments, the SSL helper in [`music_assistant/helpers/ssl.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/ssl.py) reads two optional parameters:

- **`ssl_cert`** (string, optional): Absolute path to a PEM-encoded TLS certificate.
- **`ssl_key`** (string, optional): Path to the private key corresponding to the certificate.

### Logging and Data Directories

System-level paths and verbosity are controlled by:

- **`log_level`** (string, default: `"info"`): Controls output verbosity with values including `debug`, `info`, `warning`, or `error`.
- **`data_dir`** (string, default: `"$HOME/.musicassistant"`): Root directory for the library database, cache files, and configuration storage.

## Provider-Specific Configuration

Each provider defines its own configuration schema through the `get_config_entries()` coroutine, returning tuples of `ConfigEntry` objects. Provider constants are typically defined in `music_assistant/providers/<provider>/constants.py`.

### Music Source Providers

Authentication and quality settings for streaming services vary by integration:

**YouTube Music** (`ytmusic`):
- `CONF_USERNAME`: Account email address for authentication.
- `CONF_COOKIE`: Optional secure string for authenticated requests.
- `CONF_PO_TOKEN_SERVER_URL`: Token exchange service endpoint (e.g., `"https://tokenserver.example.com"`).

**ZVuk Music** (`zvuk_music`):
- `CONF_TOKEN`: Secure API authentication token.
- `CONF_QUALITY`: Audio quality selection (`"high"`, `"medium"`, or `"low"`).

**YouSee** (`yousee`):
- `CONF_USERNAME` and `CONF_PASSWORD`: Login credentials.
- `CONF_QUALITY`: Bitrate selection as integer (`64`, `128`, or `256` KBPS).

**Yandex Ynison** (`yandex_ynison`):
- `CONF_TOKEN`: Manual Yandex token for own-mode authentication.
- `CONF_X_TOKEN`: Refresh token for QR-code login flows.
- `CONF_YM_INSTANCE`: Optional instance identifier for linking to specific Yandex Music providers.
- `CONF_MASS_PLAYER_ID`: Target player ID (or `"auto"`).
- `CONF_ALLOW_PLAYER_SWITCH`: Boolean enabling automatic player switching.
- `CONF_OUTPUT_SAMPLE_RATE` and `CONF_OUTPUT_BIT_DEPTH`: Audio output specifications (e.g., `"48000"` and `"24"`, or `"auto"`).
- `CONF_PUBLISH_NAME`: Advertised name to Yandex Music (default: `"Music Assistant"`).
- `CONF_DEVICE_ID`: Persistent device identifier for API sessions.

**Spotify Connect** (`spotify_connect`):
- `CONF_CLIENT_ID` and `CONF_CLIENT_SECRET`: Spotify developer credentials.
- `CONF_REDIRECT_URI`: OAuth callback URL (default: `"http://localhost:8095/spotify/callback"`).

### Player and Plugin Providers

Hardware and smart home integrations expose device-specific settings:

**Yandex Smart Home** (`yandex_smarthome`):
- `CONF_CONNECTION_TYPE`: Either `"cloud"` or `"direct"` connection mode.
- `CONF_INSTANCE_NAME`: Display name in the Yandex Smart Home UI.
- `CONF_CLOUD_INSTANCE_PASSWORD`, `CONF_CLOUD_CONNECTION_TOKEN`, `CONF_CLOUD_INSTANCE_ID`: Cloud authentication triplet.
- `CONF_SKILL_ID` and `CONF_SKILL_TOKEN`: Skill-specific credentials.
- `CONF_DIRECT_ACCESS_TOKEN` and `CONF_DIRECT_CLIENT_SECRET`: Direct mode security tokens.
- `CONF_EXPOSED_PLAYERS`: List of player IDs to expose to the smart home service.

**Snapcast** (`snapcast`):
- `CONF_SERVER`: Snapcast server address (e.g., `"127.0.0.1"`).
- `CONF_PORT`: Control port (default: `1704`).
- `CONF_PASSWORD`: Optional control password.

**Universal Player** (`universal_player`):
- `CONF_PLAYER_ID`: Underlying player identifier to proxy.
- `CONF_VOLUME_STEP`: Volume adjustment increment (integer, default: `5`).

## Accessing and Modifying Configuration

The configuration system supports three access patterns: YAML file editing, runtime API updates, and programmatic retrieval within provider code.

### Configuration File Locations

The primary [`config.yaml`](https://github.com/music-assistant/server/blob/main/config.yaml) resides in the data directory, containing core settings under root keys and provider entries under a `providers:` mapping. Provider-specific values use the same key names defined in their respective [`constants.py`](https://github.com/music-assistant/server/blob/main/constants.py) files.

### Runtime Access Patterns

To retrieve configuration values within a provider class, use the instance configuration object:

```python

# Inside any provider class (e.g., YtMusicProvider)

token = str(self.config.get_value(CONF_TOKEN))
quality = self.config.get_value(CONF_QUALITY)

```

For global core settings, access the mass configuration object:

```python

# Update HTTP port without manual restart

mass.config.update("port", 8080)
await mass.restart()

```

To inspect the entire configuration state for debugging:

```python
import json
print(json.dumps(mass.config.as_dict(), indent=2))

```

## Summary

- **Core settings** including `host`, `port`, `ssl_cert`, and `log_level` are defined in [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py) and stored in [`config.yaml`](https://github.com/music-assistant/server/blob/main/config.yaml).
- **Provider configurations** are declared via `get_config_entries()` in each provider's [`__init__.py`](https://github.com/music-assistant/server/blob/main/__init__.py), with keys like `CONF_TOKEN` and `CONF_QUALITY` defined in [`constants.py`](https://github.com/music-assistant/server/blob/main/constants.py).
- **Security options** include `http_password` for basic auth and `allow_remote_access` for Home Assistant connectivity.
- **Access methods** range from YAML editing to runtime Python calls using `self.config.get_value()` and `mass.config.update()`.

## Frequently Asked Questions

### How do I change the default port for Music Assistant server?

Edit the `port` key in [`config.yaml`](https://github.com/music-assistant/server/blob/main/config.yaml) (default: `8095`) or call `mass.config.update("port", 8080)` followed by `await mass.restart()` to change the HTTP API and web UI port without manual file editing.

### Where are provider authentication tokens stored in Music Assistant?

Provider tokens and credentials are stored as secure strings in the [`config.yaml`](https://github.com/music-assistant/server/blob/main/config.yaml) file under the `providers:` mapping, using keys like `CONF_TOKEN` or `CONF_PASSWORD` as defined in each provider's [`constants.py`](https://github.com/music-assistant/server/blob/main/constants.py) file.

### Can I configure Music Assistant server without using the web interface?

Yes. For headless deployments, directly edit the [`config.yaml`](https://github.com/music-assistant/server/blob/main/config.yaml) file in the data directory (default: `$HOME/.musicassistant`) or use the CLI helper with `music_assistant config set <key> <value>` for core settings, though provider-specific entries require YAML editing or API calls.

### What is the difference between core and provider configuration in Music Assistant?

Core configuration controls server-wide behavior like network binding (`host`, `port`), TLS (`ssl_cert`), and logging (`log_level`), while provider configuration manages individual music source and player settings like `CONF_USERNAME` for YouTube Music or `CONF_SERVER` for Snapcast, accessed via `self.config.get_value()`.