You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/dev-box/how-to-configure-user-customizations.md
+93-52Lines changed: 93 additions & 52 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Configure a user Customization File for Your Dev Box
3
3
description: Learn how to upload and validate user customization files for dev boxes directly from your local drive or repository.
4
-
#customer intent: As a Dev Center Admin or Project Admin, I want to create image definition files so that my development teams can create customized dev boxes.
4
+
#customer intent: As a developer, I want to upload a customization file from my local drive or repository so that I can configure my dev box with my preferred tools and scripts.
5
5
author: RoseHJM
6
6
ms.author: rosemalcolm
7
7
ms.service: dev-box
@@ -12,66 +12,78 @@ ms.custom:
12
12
- ai-seo-date:04/19/2025
13
13
- ai-gen-description
14
14
ms.topic: how-to
15
-
ms.date: 05/09/2025
15
+
ms.date: 07/16/2025
16
16
---
17
17
18
+
18
19
# Configure user customizations for dev boxes
19
20
20
-
The Dev Box user customizations feature helps you streamline the setup of your dev boxes. Starting a new project or joining a team is often complex and time consuming. With customizations, you can configure your dev boxes with the applications, tools, repositories, code libraries, packages, and build scripts that you need. This article guides you through the process of creating, testing, and editing a user customization file for your dev box using Visual Studio Code (VS Code).
21
+
You can personalize your Microsoft Dev Box by uploading a user customization file. User customization files let you configure your dev box with your preferred personal settings and apps, so you can start coding faster. This article explains how to create, test, and upload a user customization file from your local drive or repository using Visual Studio Code. You also learn how to validate your file and manage customization settings for projects.
22
+
23
+
Use customizations in Microsoft Dev Box in two ways: team customizations create a shared configuration for a team, and user customizations create a personal configuration for an individual developer. The following table shows the differences between the two types of customizations.
24
+
25
+
| Feature | Team customizations | User customizations |
| Customizations apply to | All dev boxes in pool | Individual dev box |
29
+
| Easily shareable | Yes | No |
30
+
| Customizations file name | Imagedefinition.yaml |*myfilename.yaml* or *workload.yaml*|
31
+
| Source | Catalog | Upload or personal repository |
32
+
| Supports key vault secrets | Yes | Yes |
21
33
22
-
You can use customizations in Microsoft Dev Box in two ways. Team customizations are used to create a shared configuration for a team of developers. User customizations are used to create a personal configuration for an individual developer. The following table summarizes the differences between the two types of customizations.
34
+
User customizations help ensure that developers comply with company guardrails; only tasks custom tasks preapproved through a catalog are available to developers to use in their customization files. Standard dev box users can't run built-in PowerShell and WinGet tasks in a system context, which prevents privilege escalation.
35
+
36
+
User customizations can be enabled or disabled at the project level. When you create a project, user customizations are on by default.
23
37
24
-
| Feature | Team customizations | User customizations |
| Customizations apply to | All dev boxes in pool | Individual dev box |
28
-
| Easily shareable | Yes | No |
29
-
| Customizations file name | Imagedefinition.yaml |*myfilename.yaml* or *workload.yaml*|
30
-
| Sourced from | Catalog | Uploaded or from personal repository |
31
-
| Supports key vault secrets | Yes | Yes |
32
38
33
39
## Prerequisites
34
40
35
-
To complete the steps in this article, you must:
41
+
To complete the steps in this article:
42
+
43
+
- Set up a [dev center with a dev box definition, dev box pool, and dev box project](./quickstart-configure-dev-box-service.md) so you can create a dev box.
44
+
- Join the Dev Box Users security group for at least one project.
45
+
- Attach a catalog to the dev center with tasks you use in your customization file. If you don't have a catalog, see [Add and configure a catalog from GitHub or Azure Repos](../deployment-environments/how-to-configure-catalog.md).
36
46
37
-
- Have a [dev center configured with a dev box definition, dev box pool, and dev box project](./quickstart-configure-dev-box-service.md) so that you can create a dev box.
38
-
- Be a member of the Dev Box Users security group for at least one project.
39
-
- Have a catalog attached to the dev center with tasks that you can use in your customization file. If you don't have a catalog, see [Add and configure a catalog from GitHub or Azure Repos](../deployment-environments/how-to-configure-catalog.md).
40
47
41
-
## Permissions required to configure customizations
42
-
43
-
To perform the required actions for creating and applying customizations to a dev box, you need the following permissions:
| Enable or disable user customizations on a project | Write permission on the project. |
55
+
| Create a customization file | None specified. Anyone can create a customization file. |
56
+
| Use the developer portal to upload and apply a YAML file during dev box creation | Dev Box User |
50
57
51
58
## Create a user customization file
52
59
53
-
You can create and manage customization files by using VS Code. You can use the Microsoft Dev Box extension in VS Code to discover the tasks in the attached catalog and test the customization file.
60
+
Create and manage customization files in VS Code. Use the Microsoft Dev Box extension in VS Code to discover tasks in the attached catalog and test the customization file.
54
61
55
-
1. Create a dev box (or use an existing dev box) for testing.
56
-
1. On the test dev box, install VS Code and then install the [Dev Box extension](https://marketplace.visualstudio.com/items?itemName=DevCenter.ms-devbox).
57
-
1. Download an [example YAML customization file](https://aka.ms/devbox/usercustomizations/samplefile) from the samples repository and open it in VS Code.
58
-
1. Discover tasks available in the catalog by using the command palette. Select **View** > **Command Palette** > **Dev Box: List Available Tasks For This Dev Box**.
62
+
1. Create a dev box for testing, or use an existing dev box.
63
+
64
+
1. On the test dev box, install VS Code, then install the [Dev Box extension](https://marketplace.visualstudio.com/items?itemName=DevCenter.ms-devbox).
65
+
66
+
1. Download an [example YAML customization file](https://aka.ms/devbox/usercustomizations/samplefile) from the samples repository, then open it in VS Code.
67
+
68
+
1. Discover available tasks in the catalog by using the command palette. Select **View** > **Command Palette** > **Dev Box: List Available Tasks For This Dev Box**.
59
69
60
70
:::image type="content" source="media/how-to-configure-user-customizations/dev-box-command-list-tasks.png" alt-text="Screenshot of the Dev Box command palette in Visual Studio Code, showing the command for listing available tasks.":::
61
71
62
-
1. Test customization in VS Code by using the command palette. Select **View** > **Command Palette** > **Dev Box: Apply Customizations Tasks**.
72
+
1. Test the customization in VS Code by using the command palette. Select **View** > **Command Palette** > **Dev Box: Apply Customizations Tasks**.
63
73
64
74
:::image type="content" source="media/how-to-configure-user-customizations/dev-box-command-apply-tasks.png" alt-text="Screenshot of the Dev Box command palette in Visual Studio Code, showing the command for applying customization tasks.":::
65
75
66
-
1. The customization file runs and applies the specified tasks to your test dev box. Inspect the changes, and check the VS Code terminal for any errors or warnings generated during the task execution. Review the VS Code terminal for errors or warnings during task execution.
76
+
1. The customization file runs and applies the specified tasks to your test dev box. Inspect the changes, and check the VS Code terminal for any errors or warnings during task execution.
77
+
78
+
1. After the customization file runs successfully, upload it to your catalog.
79
+
67
80
68
-
1. When the customization file runs successfully, upload it to your catalog.
81
+
### Optional: Customize your dev box by using existing WinGet configuration files
69
82
70
-
### Optional: Customize your dev box by using existing WinGet Configuration files
83
+
WinGet configuration uses a config-as-code approach to define the unique sets of software and configuration settings needed to get your Windows environment ready to code. You can also use these configuration files to set up a dev box by using a WinGet task included in the Microsoft-provided quickstart catalog.
71
84
72
-
WinGet configuration takes a config-as-code approach to defining the unique sets of software and configuration settings needed to get your Windows environment in a ready-to-code state. You can also use these configuration files to set up a dev box, by using a WinGet task included in the Microsoft-provided quickstart catalog.
85
+
This example shows a dev box customization file that uses an existing WinGet Desired State Configuration (DSC) file.
73
86
74
-
This example shows a dev box customization file that uses an existing WinGet Desired State Configuration (DSC) file:
75
87
76
88
```yml
77
89
tasks:
@@ -80,50 +92,79 @@ tasks:
80
92
configure: "projectConfiguration.dsc.yaml"
81
93
```
82
94
95
+
83
96
To learn more, see [WinGet configuration](https://aka.ms/winget-configuration).
84
97
98
+
85
99
## Create a dev box using a user customization file
86
100
87
-
You can use an individual customization file by uploading it from a local drive when creating your dev box, or by downloading it from a repository.
88
-
Customization files stored in a repository must be called *workload.yaml*. Customization files that are stored locally for upload should be called *myfilename.yaml*. Name customization files stored locally for upload as *myfilename.yaml*.
101
+
Use an individual customization file by uploading it from a local drive when you create your dev box, or by downloading it from a repository.
102
+
Customization files stored in a repository must be named *workload.yaml*. Customization files stored locally for upload should be named *myfilename.yaml*.
89
103
90
104
### Upload a file
105
+
91
106
1. In the [developer portal](https://aka.ms/devbox-portal), select **New** > **New dev box**.
92
-
1. In the **Add a dev box** pane, add details for you dev box.
107
+
108
+
1. In the **Add a dev box** pane, add details for your dev box.
109
+
93
110
1. Select **Apply customizations**, and then select **Continue**.
94
111
95
112
:::image type="content" source="media/how-to-configure-user-customizations/add-dev-box-individual-customization.png" alt-text="Screenshot of the Add a dev box pane in the developer portal, showing the option to apply customizations.":::
96
-
97
-
1. Select **Upload a customization file(s)**, select **Add customizations from file**, and then browse to and select your *myfilename.yaml* file.
113
+
114
+
1. Select **Upload a customization file(s)**, select **Add customizations from file**, then browse to and select your *myfilename.yaml* file.
98
115
99
116
:::image type="content" source="media/how-to-configure-user-customizations/customize-dev-box-upload.png" alt-text="Screenshot of the Upload a customization file section in the developer portal, showing the option to add customizations from a file.":::
100
-
101
-
1. To verify that the tasks in your customizations file will be applied correctly, you must validate them before you can proceed. Select **Validate**.
117
+
118
+
1. To check that the tasks in your customizations file are applied correctly, validate them before you proceed. Select **Validate**.
102
119
103
120
:::image type="content" source="media/how-to-configure-user-customizations/customize-dev-box-validate.png" alt-text="Screenshot of the Validate button in the developer portal, showing the option to validate the customization file before proceeding.":::
104
-
105
-
1. Review the dev box creation summary, and then select **Create**.
106
-
107
-
:::image type="content" source="media/how-to-configure-user-customizations/customized-dev-box-create.png" alt-text="Screenshot of the dev box creation summary page in the developer portal, showing the option to create a customized dev box.":::
121
+
122
+
1. Review the dev box creation summary, then select **Create**.
123
+
124
+
:::image type="content" source="media/how-to-configure-user-customizations/customized-dev-box-create.png" alt-text="Screenshot of the dev box creation summary page in the developer portal, showing the option to create a customized dev box.":::
108
125
109
126
### Get a file from a repository
127
+
110
128
1. In the [developer portal](https://aka.ms/devbox-portal), select **New** > **New dev box**.
129
+
111
130
1. In the **Add a dev box** pane, add details for you dev box.
131
+
112
132
1. Select **Apply customizations**, and then select **Continue**.
113
133
114
134
:::image type="content" source="media/how-to-configure-user-customizations/add-dev-box-individual-customization.png" alt-text="Screenshot of the Add a dev box pane in the developer portal, showing the option to apply customizations.":::
115
-
116
-
1. Select **Upload a customization file(s)**, select **Choose a customization file from a repository**, and then enter the URL for the repository that stores your *workload.yaml* file.
135
+
136
+
1. Select **Upload a customization file(s)**, select **Choose a customization file from a repository**, then enter the URL for the repository that stores your *workload.yaml* file.
117
137
118
138
:::image type="content" source="media/how-to-configure-user-customizations/customize-dev-box-from-repository.png" alt-text="Screenshot of the Choose a customization file from a repository section in the developer portal, showing the option to enter a repository URL.":::
119
-
120
-
1. To verify that the tasks in your customizations file will be applied correctly, you must validate them before you can proceed. Select **Validate**.
139
+
140
+
1. To verify that the tasks in your customizations file will be applied correctly, validate them before you proceed. Select **Validate**.
121
141
122
142
:::image type="content" source="media/how-to-configure-user-customizations/customize-dev-box-validate.png" alt-text="Screenshot of the Validate button in the developer portal, showing the option to validate the customization file before proceeding.":::
123
-
143
+
124
144
1. Review the dev box creation summary, and then select **Create**.
125
-
126
-
:::image type="content" source="media/how-to-configure-user-customizations/customized-dev-box-create.png" alt-text="Screenshot of the dev box creation summary page in the developer portal, showing the option to create a customized dev box.":::
145
+
146
+
:::image type="content" source="media/how-to-configure-user-customizations/customized-dev-box-create.png" alt-text="Screenshot of the dev box creation summary page in the developer portal, showing the option to create a customized dev box.":::
147
+
148
+
149
+
## Disable user customizations
150
+
151
+
User customizations are controlled at the project level and are enabled by default. You can disable them during or after project creation. When disabled, developers can't apply their own customization files to new dev boxes. Enabling user customizations doesn't bypass existing project guardrails; developers can only use tasks provided in the attached catalog and cannot run tasks with elevated privileges unless an administrator has explicitly included an administrative task in the catalog.
152
+
153
+
:::image type="content" source="media/how-to-configure-user-customizations/user-customizations-enabled.png" alt-text="Screenshot of a dev box project showing the user customizations feature enabled in the dev box settings." lightbox="media/how-to-configure-user-customizations/user-customizations-enabled.png":::
154
+
155
+
Currently, when you disable user customizations for a project, developers can still upload a user customization file during dev box creation. But the validation process fails, and the customizations aren't applied to the dev box.
156
+
157
+
If you create a dev box with user customizations in a project where user customizations are disabled, you see the following in the developer portal:
158
+
159
+
1. A message displays on the new dev box tile indicating that errors have been encountered while applying customizations.
160
+
161
+
:::image type="content" source="media/how-to-configure-user-customizations/user-customizations-disabled-tile-error.png" alt-text="Screenshot of a dev box tile showing the message We encountered errors while applying customizations. A See details button is highlighted.":::
162
+
163
+
1. The details advise you to contact your admin.
164
+
165
+
:::image type="content" source="media/how-to-configure-user-customizations/user-customizations-disabled-error-details.png" alt-text="Screenshot of the error details pane in the developer portal, displaying a message that customizations failed and advising the user to contact their administrator.":::
166
+
167
+
1. Your dev box is created without the user customizations.
0 commit comments