The msksd configuration file¶

msksd reads its settings from a YAML file, from MSKSD_* environment variables, and from built-in defaults. The file is the durable home for a deployment's settings, committed to the deployment's own storage and human-reviewable, while the environment variables stay available as per-invocation overrides.

Precedence¶

Values resolve in this order (highest first):

1. Environment variables (MSKSD_*) — override the file
2. The config file — the YAML file msksd resolves at startup
3. Built-in defaults — the settings dataclass defaults

A variable set in the process wins over the same key in the file; a key set nowhere uses the default. An environment variable set to an empty string is the unset form: the file value applies.

The --config flag¶

msksd resolves its config file in three modes:

MSKSD_CONFIG_DIR is read before anything else and exists only as an environment variable: the config file cannot relocate the directory it lives in, so the tree root must be resolvable before the file is located.

msksd doctor¶

msksd doctor checks the host for the tools the daemon and the client exec, reading the config the same way the daemon does — the --config flag, the environment, and the file, under the precedence above. The host doctor chapter owns the check rows, the report's markers and hints, and the exit codes.

Key mapping¶

A config-file key is its MSKSD_* variable with the prefix stripped and lowercased, one rule with no lookup table:

The file is flat: one key per setting, no sections. For example:

host: 0.0.0.0
port: 8660

sets the same settings MSKSD_HOST, MSKSD_PORT, and MSKSD_CONSOLE_WAIT_TIMEOUT_S would. Either spelling is recoverable from the other by the rule, and the daemon enforces it in code: the key↔variable table is derived mechanically, so the two forms cannot drift apart.

The underscore is the canonical spelling, and a hyphen may be written for it: egress-dns-upstream and egress_dns_upstream are one key spelled two ways. The llm_models entries' keys follow the same rule, so an operator used to kebab-case YAML can write it naturally. Both spellings of one key in the same file is a startup error naming the two spellings, and the valid-keys list an unknown key reports is the snake_case one.

One mapping detail worth knowing: state_dir places the database too. state_dir feeds both the local driver's workspace artifacts and the server's sqlite database (<state_dir>/msks.db); there is no separate db_path key, matching the environment variable, which also drives both.

Native scalar types¶

Numeric, boolean, and string fields accept their natural YAML scalars: port: 8660, access_log: true, socket_wait_timeout_s: 12.5. Quoted strings (port: "8660") work everywhere and parse identically. A key with no value (bootstrap_token:) is the unset form; the environment (for its variable) and then the default apply. Values must be scalars: a list or mapping where a number, boolean, or string belongs is a startup error, and so is a duplicate key: a second port: does not silently win. Merge keys (<<: *anchor) are refused with their own message: the file is flat and every key is spelled out.

Booleans deserve care. true and false are the spellings to use; PyYAML also parses the YAML 1.1 forms yes/no/on/off as booleans, so those work too. The single letters y and n are plain strings to YAML 1.1, so a boolean key set to either reads as false; the environment variable follows the same string rule. A bare 1 or 0 is an integer, which also reads as false. Write true or false.

Unknown keys fail fast¶

A key the daemon does not know is a startup error naming the key and the valid ones, so a typo'd prot fails at boot instead of being silently ignored. The environment has no such guard: a typo'd variable name is simply never read. Invalid values fail the same way whichever source they came from, and the error message names the MSKSD_* variable — vmm_driver: firecracker reports MSKSD_VMM_DRIVER must be one of ('local',). Non-finite numbers (.nan, .inf) are rejected from either source.

Key reference¶

The tables below group the keys by the subsystem that reads them; the file itself carries them all at one level.

The API listener¶

The local cloud-hypervisor driver¶

Per-workspace egress networking¶

Host share mounts¶

Host paths are the one share surface (mounts chapter for the behavior): a workspace names a host directory through the daemon's two gates, and this table is the second one's config. The named-share list (mount_shares) was removed — a config that still names the key fails at load with the removal message pointing at these keys.

The placeholder secret store¶

Where the real secrets behind placeholder tokens live (secrets chapter for the flow). The store is one per-recipient ciphertext blobs; plaintext returns only through an operator's unlock when the first store operation finds it absent.

SIGHUP reload¶

Send SIGHUP to a running msksd and it re-reads the config file (and the environment) into its live settings. Subsystems read settings off the app's state at call time, so the swap propagates with no per-module reconfiguration: a changed egress_subnet or host_name applies to the next request that reads it.

Several things keep their startup values until a restart. A reload naming a new one changes nothing:

• the listener's address, port, TLS material, and access logging, all bound at startup; the access log is also snapshotted into the listener's config
• state_dir and the database path it places: the engine is open, and the local driver resolves every workspace's artifacts from the state dir live, so the daemon latches the startup value (moving it mid-run would orphan running workspaces)
• default_image (imported into the catalog once, at first boot)
• the watcher scan's event_poll_s (sampled at loop start): both the workspace status reconcile and the state-disk pressure probe ride it
• the egress machinery's startup inputs. egress_enabled latches the subsystem's state when the daemon boots. The base NAT masquerade's egress_uplink also latches: per-workspace firewall rules read the live setting, but the base table that actually masquerades out the uplink keeps its startup value, so change egress_uplink only with a restart scheduled.

One reload does re-stamp the base table. A change that alters the LLM proxy's loopback guard shape (llm_models gaining or losing entries, llm_port, egress_subnet) re-applies the table at the next workspace start, masquerade included, from the live egress_uplink.

mount_host_roots reads live after a reload: each workspace's next start derives its attachments from the roots the reload left — a root the reload removed reads as a skip at start (the mounts chapter names the skip behavior). Running VMs keep the devices they attached. virtiofsd reads live too: the next start spawns the binary the reload names.

A config that fails to load or validate is refused: the daemon reports the error on stderr and keeps the previous settings. A default-path file deleted since startup is likewise refused rather than regenerated, because a reload is not a first run and regenerating the template would silently revert every file-set value to its default.