Drive Mappings

The session.driveMappings array mounts Windows drives inside the user session — an SMB share, a host path, or a WebStream virtual share. Mounts are scoped to the session and removed at logoff.

Editor Drive Mappings accordion · JSON session.driveMappings[]

The drive-mappings table: one row per mapping with letter, type, target, credentials and mount options.

Core fields (schema)

Each array entry is an object. The first five fields are required.

Property	Type	Default	Rules / notes
`enabled` *	boolean	true	Whether this mapping is active.
`name` *	string	—	Min length 1. Shown in the client UI.
`driveLetter` *	string	—	Single letter, pattern `^[D-Zd-z]$` (A/B/C reserved by Windows). Letters must be unique across mappings.
`type` *	enum	—	`smb`: UNC share; `localpath`: host path via SMB loopback; `virtualshare`: a WebStream virtual share via SMB loopback.
`target` *	string	—	Min length 1. `smb`: `\\server\share`; `localpath`: `D:\path`; `virtualshare`: a share name from `security.fileSystem.virtualShares`. Supports macros (below).

Credentials

Property	Type	Default	Rules / notes
`username`	string	—	Optional SMB credentials, e.g. `DOMAIN\user`. Omit for integrated auth.
`passwordRef`	string	—	Secret reference. Pattern `^(dpapi:\|env:).+` — either `dpapi:<base64>` (machine-scope DPAPI) or `env:<VARNAME>`. Plaintext is rejected.

Mount behaviour

Property	Type	Default	Min / max	Notes
`reconnect`	boolean	false	—	Auto-remount on network-change events (laptop sleep, host network blip).
`readOnly`	boolean	false	—	Mount read-only (enforced via share permissions and NTFS ACL where possible).
`quotaMB`	integer	—	min 0	Optional disk quota (best-effort; requires FSRM on the host).
`persistOnDisconnect`	boolean	true	—	Keep the mapping on disconnect (`true`) or drop it (`false`). Always removed on logoff.
`mountTimeoutMs`	integer	15000	1000 – 60000	Per-mapping mount timeout, in milliseconds.
`mountMode`	enum	eager	—	`eager`: mount at session start. `lazy`: reserve the letter, mount on first access. `blocking` (runtime): session start waits for the mount.
`failFastReach`	boolean	true	—	Run a 500 ms TCP/445 reachability probe before mounting to fail fast on unreachable targets.

In the editor the Required checkbox maps to mountMode: checked = blocking, unchecked = eager. The fields quotaMB, persistOnDisconnect, mountTimeoutMs, failFastReach and the lazy mount mode are set only through the Advanced Session JSON.

Runtime extensions

These fields are supported by the runtime and the editor but are not part of the published JSON schema.

Property	Type	Default	Notes
`autoCreateTarget`	boolean	false	Create the target directory if missing. Disabled for `virtualshare`.
`volumeLabel`	string	—	Override the mounted volume label. Max 32 characters.
`volumeSerialHex`	string	—	Override the volume serial. 8 hex digits.
`envVars`	object	—	String→string map of environment variables (macro values supported) injected for the mapping.

Target macros

The target (and envVars values) support substitution at session start:

$USERNAME $SESSIONID $TENANT $DOMAIN $DATE ${NAME}

Sample

"driveMappings": [
  {
    "enabled": true,
    "name": "Team Share",
    "driveLetter": "P",
    "type": "smb",
    "target": "\\\\files.example.com\\teams\\$USERNAME",
    "username": "EXAMPLE\\svc_webstream",
    "passwordRef": "dpapi:AQAAAN...",
    "reconnect": true,
    "readOnly": false,
    "mountMode": "eager",
    "failFastReach": true
  }
]

Note

Drive mappings are policy-only — there is no app.config.xml equivalent. Secrets must be DPAPI- or environment-referenced; plaintext passwords are rejected at parse time.