Repository: viamrobotics/docs
Pull request #4245: DOCS-3905: Add Windows viam-agent management instructions
Author: login: JessamyT
Labels: name: safe to build
description: This pull request is marked safe to build from a trusted zone
Created: 2025-04-22T20:54:15Z | Merged: 2025-04-23T21:46:27Z



Diff:
diff --git a/assets/manage/startup-type-windows.png b/assets/manage/startup-type-windows.png
new file mode 100644
index 0000000000..2ffd198159
Binary files /dev/null and b/assets/manage/startup-type-windows.png differ
diff --git a/assets/manage/viam-agent-windows-services-manager.png b/assets/manage/viam-agent-windows-services-manager.png
new file mode 100644
index 0000000000..a3b5ef4b49
Binary files /dev/null and b/assets/manage/viam-agent-windows-services-manager.png differ
diff --git a/docs/manage/reference/viam-agent/manage-viam-agent.md b/docs/manage/reference/viam-agent/manage-viam-agent.md
index cbb527e280..57b2adf6c0 100644
--- a/docs/manage/reference/viam-agent/manage-viam-agent.md
+++ b/docs/manage/reference/viam-agent/manage-viam-agent.md
@@ -16,6 +16,9 @@ aliases:
 
 [`viam-agent`](/manage/reference/viam-agent/) is installed as a `systemd` service named `viam-agent`.
 
+{{< tabs >}}
+{{% tab name="Linux" %}}
+
 - To start `viam-agent`:
 
   ```sh {class="command-line" data-prompt="$"}
@@ -50,6 +53,65 @@ aliases:
 
   This command uninstalls `viam-agent`, `viam-server`, the machine cloud credentials file (<file>/etc/viam.json</file>), and the provisioning configuration file (<file>/etc/viam-provisioning.json</file>).
 
+{{% /tab %}}
+{{% tab name="Windows native" %}}
+
+On Windows, you can manage `viam-agent` using the Services GUI or the command line:
+
+{{< tabs >}}
+{{% tab name="Services GUI" %}}
+
+1. Open the **Services** management console from your computer's start menu.
+
+1. Find `viam-agent` in the list of services.
+
+   {{<imgproc src="/manage/viam-agent-windows-services-manager.png" resize="x1100" declaredimensions=true alt="Windows Services manager with viam-agent highlighted." style="max-width:600px" class="shadow imgzoom" >}}
+
+1. Use the **Start Service**, **Stop Service**, and **Restart Service** buttons to manage `viam-agent`.
+
+1. To change the startup type of `viam-agent`, right-click on `viam-agent` and select **Properties**.
+   Select your desired startup type from the **Startup type** dropdown menu.
+
+   {{<imgproc src="/manage/startup-type-windows.png" resize="x1000" declaredimensions=true alt="Windows Services manager with viam-agent properties open." style="max-width:350px" class="shadow imgzoom" >}}
+
+{{% /tab %}}
+{{% tab name="Command line" %}}
+
+1. Open a PowerShell prompt, selecting **Run as administrator**.
+
+1. Use the following commands to manage `viam-agent`:
+
+   - To start `viam-agent`:
+
+     ```sh {class="command-line" data-prompt="$"}
+     Start-Service viam-agent
+     ```
+
+   - To stop `viam-agent`:
+
+     ```sh {class="command-line" data-prompt="$"}
+     Stop-Service viam-agent
+     ```
+
+   - To restart `viam-agent`:
+
+     ```sh {class="command-line" data-prompt="$"}
+     Restart-Service viam-agent
+     ```
+
+   - To change the startup type of `viam-agent`, use one of the following commands:
+
+     ```sh {class="command-line" data-prompt="$"}
+     Set-Service -Name "viam-agent" -StartupType Manual
+     Set-Service -Name "viam-agent" -StartupType Automatic
+     ```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+{{% /tab %}}
+{{< /tabs >}}
+
 ## Troubleshooting
 
 You can find assistance in the [Troubleshooting section](/manage/troubleshoot/troubleshoot/).


Reviews:
user: login: npentrel
body: Thank you, very nice
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-23T08:50:59Z
user: login: nathan-contino
body: LGTM % a question and a very optional suggestion
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-23T12:56:02Z
user: login: JessamyT
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-23T19:33:14Z
user: login: JessamyT
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-23T19:36:50Z

Review comments:
diff_hunk: @@ -50,6 +53,60 @@ aliases:
 
   This command uninstalls `viam-agent`, `viam-server`, the machine cloud credentials file (<file>/etc/viam.json</file>), and the provisioning configuration file (<file>/etc/viam-provisioning.json</file>).
 
+{{% /tab %}}
+{{% tab name="Windows native" %}}
+
+On Windows, you can manage `viam-agent` using the Services GUI or the command line.
+
+## Manage `viam-agent` using the Services GUI
+
+1. Open the **Services** management console from your computer's start menu.
path: docs/manage/reference/viam-agent/manage-viam-agent.md
user: login: nathan-contino
body: [opt] reverse the order of this phrasing so readers don't have to double back:

```suggestion
1. In your computer's start menu, open the **Services** management console.
```

Disclaimer: I haven't used Windows since 10, so maybe the original order was more natural?
created_at: 2025-04-23T12:53:28Z
author_association: CONTRIBUTOR
diff_hunk: @@ -50,6 +53,60 @@ aliases:
 
   This command uninstalls `viam-agent`, `viam-server`, the machine cloud credentials file (<file>/etc/viam.json</file>), and the provisioning configuration file (<file>/etc/viam-provisioning.json</file>).
 
+{{% /tab %}}
+{{% tab name="Windows native" %}}
+
+On Windows, you can manage `viam-agent` using the Services GUI or the command line.
+
+## Manage `viam-agent` using the Services GUI
+
+1. Open the **Services** management console from your computer's start menu.
+
+1. Find `viam-agent` in the list of services.
+
+   {{<imgproc src="/manage/viam-agent-windows-services-manager.png" resize="x1100" declaredimensions=true alt="Windows Services manager with viam-agent highlighted." style="max-width:600px" class="shadow imgzoom" >}}
+
+1. Use the **Start Service**, **Stop Service**, and **Restart Service** buttons to manage `viam-agent`.
+
+1. To change the startup type of `viam-agent`, right-click on `viam-agent` and select **Properties**.
+   Select your desired startup type from the **Startup type** dropdown menu.
+
+   {{<imgproc src="/manage/startup-type-windows.png" resize="x1000" declaredimensions=true alt="Windows Services manager with viam-agent properties open." style="max-width:350px" class="shadow imgzoom" >}}
+
+## Manage `viam-agent` using the command line
path: docs/manage/reference/viam-agent/manage-viam-agent.md
user: login: nathan-contino
body: [q] why use sections within the Windows Native tab for CLI/GUI when those operations are (generally speaking) mutually exclusive? I would expect these parallel operations in tabs, but maybe we don't like stacking tabs that deep?
created_at: 2025-04-23T12:55:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -50,6 +53,60 @@ aliases:
 
   This command uninstalls `viam-agent`, `viam-server`, the machine cloud credentials file (<file>/etc/viam.json</file>), and the provisioning configuration file (<file>/etc/viam-provisioning.json</file>).
 
+{{% /tab %}}
+{{% tab name="Windows native" %}}
+
+On Windows, you can manage `viam-agent` using the Services GUI or the command line.
+
+## Manage `viam-agent` using the Services GUI
+
+1. Open the **Services** management console from your computer's start menu.
path: docs/manage/reference/viam-agent/manage-viam-agent.md
user: login: JessamyT
body: In general I'd go with your wording because if someone needs to go to a page before finding a button, it's better to say it in that order instead of "find the x button on the page you didn't know until now you should be on". But in this case I prefer it this way because they don't need to look for something that says "start"--they just need to find "Services" in the natural way, so the emphasis can be there.
created_at: 2025-04-23T19:33:14Z
author_association: CONTRIBUTOR
diff_hunk: @@ -50,6 +53,60 @@ aliases:
 
   This command uninstalls `viam-agent`, `viam-server`, the machine cloud credentials file (<file>/etc/viam.json</file>), and the provisioning configuration file (<file>/etc/viam-provisioning.json</file>).
 
+{{% /tab %}}
+{{% tab name="Windows native" %}}
+
+On Windows, you can manage `viam-agent` using the Services GUI or the command line.
+
+## Manage `viam-agent` using the Services GUI
+
+1. Open the **Services** management console from your computer's start menu.
+
+1. Find `viam-agent` in the list of services.
+
+   {{<imgproc src="/manage/viam-agent-windows-services-manager.png" resize="x1100" declaredimensions=true alt="Windows Services manager with viam-agent highlighted." style="max-width:600px" class="shadow imgzoom" >}}
+
+1. Use the **Start Service**, **Stop Service**, and **Restart Service** buttons to manage `viam-agent`.
+
+1. To change the startup type of `viam-agent`, right-click on `viam-agent` and select **Properties**.
+   Select your desired startup type from the **Startup type** dropdown menu.
+
+   {{<imgproc src="/manage/startup-type-windows.png" resize="x1000" declaredimensions=true alt="Windows Services manager with viam-agent properties open." style="max-width:350px" class="shadow imgzoom" >}}
+
+## Manage `viam-agent` using the command line
path: docs/manage/reference/viam-agent/manage-viam-agent.md
user: login: JessamyT
body: It's a good question, and part of a larger convo about usage of tabs and expanders. I like both tabs and expanders but some people prefer seeing all the things in plain sight. Also our tabs aren't searchable with command f. But in this case it's all already in a tab and yes they are mutually exclusive so I will change to tabs!
created_at: 2025-04-23T19:36:49Z
author_association: CONTRIBUTOR

PR comments:
user: login: netlify[bot]
created_at: 2025-04-22T20:54:33Z
body: ### <span aria-hidden="true">✅</span> Deploy Preview for *viam-docs* ready!


|  Name | Link |
|:-:|------------------------|
|<span aria-hidden="true">🔨</span> Latest commit | 6c138426ba0b5aa60d35323adc28b33482cb4ef2 |
|<span aria-hidden="true">🔍</span> Latest deploy log | https://app.netlify.com/sites/viam-docs/deploys/68095eee4a0ab90008757315 |
|<span aria-hidden="true">😎</span> Deploy Preview | [https://deploy-preview-4245--viam-docs.netlify.app](https://deploy-preview-4245--viam-docs.netlify.app) |
|<span aria-hidden="true">📱</span> Preview on mobile | <details><summary> Toggle QR Code... </summary><br /><br />![QR Code](https://app.netlify.com/qr-code/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1cmwiOiJodHRwczovL2RlcGxveS1wcmV2aWV3LTQyNDUtLXZpYW0tZG9jcy5uZXRsaWZ5LmFwcCJ9.CdmNMfSi_Z_EJaXMQkz80y7KKwkO9yjV6AtR6t0RHRQ)<br /><br />_Use your smartphone camera to open QR code link._</details> |
|<span aria-hidden="true">![Lighthouse](https://app.netlify.com/public/external-usage/git-comments/lighthouse-sm.png)</span><br />Lighthouse | 1 paths audited<br />**Performance**: 45 (🟢 up 3 from production)<br />**Accessibility**: 100 (no change from production)<br />**Best Practices**: 100 (no change from production)<br />**SEO**: 92 (no change from production)<br />**PWA**: 70 (no change from production)<br />[View the detailed breakdown and full score reports](https://app.netlify.com/sites/viam-docs/deploys/68095eee4a0ab90008757315) |
---
<!-- [viam-docs Preview](https://deploy-preview-4245--viam-docs.netlify.app) -->
_To edit notification comments on pull requests, go to your [Netlify site configuration](https://app.netlify.com/sites/viam-docs/configuration/notifications#deploy-webhooks)._
author_association: NONE
user: login: github-actions[bot]
created_at: 2025-04-23T21:47:01Z
body: :mag_right::speech_balloon: [Inkeep](https://inkeep.com) AI search and chat service is syncing content for source 'Viam Docs'
author_association: NONE