Dev Container Detection
Relevant source files
The following files were used as context for generating this wiki page:
Dev Container Detection is a core feature of vscli that allows the tool to automatically identify, parse, and launch Visual Studio Code development containers. The system scans workspace directories for standardized configuration files and determines the appropriate environment (local or containerized) based on user-defined strategies and discovered assets.
The detection logic mimics the behavior of Visual Studio Code to ensure compatibility, supporting both single and multiple dev container configurations within a single project. It handles path translation, variable substitution, and URI encoding required to interface with the vscode-remote protocol.
Sources: README.md:12-16, src/workspace.rs:135-141
Detection Algorithm and Logic
The detection process follows a prioritized workflow to identify which development container configuration should be used for a given workspace.
Discovery Workflow
The discovery logic searches for devcontainer.json files in specific locations relative to the workspace root. It uses the following priority:
- Manual Override: If a configuration path is explicitly provided via the
--configflag, that file is used immediately. - Direct Root Config: A
.devcontainer.jsonfile located directly in the workspace root. - Standard Directory: A
devcontainer.jsonfile located inside a.devcontainer/folder. - Nested Configs: Any
devcontainer.jsonfile found one level deep within the.devcontainer/subfolders (e.g.,.devcontainer/rust/devcontainer.json).
Sources: src/workspace.rs:142-171, src/launch.rs:101-106, README.md:143-150
Decision Flow Diagram
The following diagram illustrates the decision logic used by the Setup::detect and Setup::launch methods to determine the final dev container configuration.
Configuration Parsing and Variable Substitution
Once a configuration file is identified, it is parsed as JSON5 to allow for comments and trailing commas. The system extracts specific metadata to configure the container environment.
DevContainer Data Structure
The DevContainer struct represents the parsed state of a configuration:
| Field | Type | Description |
|---|---|---|
config_path | PathBuf | The local filesystem path to the json config. |
name | Option<String> | The display name defined in the config. |
workspace_path_in_container | String | The path where the workspace is mounted inside the container. |
Sources: src/workspace.rs:11-16
Path Variables
The system supports substituting variables within the workspaceFolder field of the configuration to ensure the workspace mounts correctly:
${localWorkspaceFolderBasename}: Replaced with the name of the local workspace directory.${localWorkspaceFolder}: Defaults to/workspaces/<workspace_name>.
Sources: src/workspace.rs:67-92
Remote URI Generation
To launch a dev container, vscli constructs a specialized vscode-remote URI. This involves encoding host paths and configuration paths into a JSON structure, which is then hex-encoded.
URI Components
- JSON Payload: A
DevcontainerUriJsonobject containing thehostPathand aconfigFile(represented as aFileUriJson). - Hex Encoding: The JSON payload is converted to bytes and hex-encoded.
- Protocol String: The final URI follows the format:
vscode-remote://dev-container+<HEX_JSON><CONTAINER_FOLDER_PATH>.
Sources: src/workspace.rs:245-255, src/uri.rs:31-38
Sequence of URI Construction
Sources: src/workspace.rs:207-258
Launch Strategies
The detection system is governed by a ContainerStrategy which determines how the tool responds to the presence or absence of dev container configurations.
| Strategy | Behavior |
|---|---|
detect | (Default) Launches dev container if found; otherwise launches classic vscode. |
force-container | Attempts to launch dev container; fails with an error if none is found. |
force-classic | Ignores any existing dev container configurations and launches on the host system. |
Sources: src/launch.rs:25-42, README.md:136-141
Implementation Details
Relevant Functions
Workspace::find_dev_container_configs: Implements the filesystem scanning logic. src/workspace.rs:142DevContainer::from_config: Handles JSON parsing and variable substitution. src/workspace.rs:34Setup::launch: Executes the primary logic for matching strategies to discovered containers. src/launch.rs:125FileUriJson::new: Handles the conversion of system paths to URI-compatible file schemes, including special handling for Windows paths and backslashes. src/uri.rs:12
Environment Handling (WSL)
On Unix systems, the detection logic includes a check for Windows Subsystem for Linux (WSL). If WSL is detected (via uname -a and the WSLENV variable), the tool uses wslpath2 to convert local Linux paths into Windows-style paths before URI encoding, as the VS Code host application often runs on the Windows side.
Sources: src/workspace.rs:218-243
Summary
Dev Container Detection in vscli provides a robust mechanism for bridge-building between local filesystems and containerized development environments. By automating the discovery of .devcontainer.json files and managing the complexities of hex-encoded remote URIs and cross-platform pathing, it simplifies the transition into container-based workflows.