Skip to content

DOCS-4639 Document support for viam-agent on MacOS #4829

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shannonbradshaw merged 2 commits into from
Mar 5, 2026
Merged

DOCS-4639 Document support for viam-agent on MacOS #4829

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a40e288
Update index page
benjirewis Mar 2, 2026
2da889e
Update 'manage viam agent' docs
benjirewis Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 12 additions & 5 deletions docs/manage/reference/viam-agent/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Among other things, `viam-agent`:
- Provides various operating system settings.

{{< alert title="Support notice" color="note" >}}
Currently, `viam-agent` is only supported on Linux for amd64 (x86_64) and arm64 (aarch64) CPUs and Windows (native).
Currently, `viam-agent` is only supported on Linux for amd64 (x86_64) and arm64 (aarch64) CPUs, MacOS for arm64 (M/silicon) CPUs, and Windows (native).
{{< /alert >}}

To provision machines using `viam-agent`, see [Provision Machines](/manage/fleet/provision/setup/).
Expand All @@ -46,7 +46,7 @@ Follow the instructions to install `viam server` with `viam-agent`.
Your machine must have `curl` available in order to install `viam-agent`.

{{< tabs >}}
{{% tab name="Linux" %}}
{{% tab name="Linux/MacOS" %}}

You can use `viam-agent` either with

Expand Down Expand Up @@ -74,7 +74,8 @@ You can get the machine cloud credentials by clicking the copy icon next to **Ma
{{% /tab %}}
{{< /tabs >}}

On Linux, `viam-agent` will install itself as a systemd service named `viam-agent`.
On Linux, `viam-agent` will install itself as a systemd service named `viam-agent`. On MacOS, `viam-agent` will install itself as a launchd daemon named `system/com.viam.agent`.

For information on managing the service, see [Manage `viam-agent`](/manage/reference/viam-agent/manage-viam-agent/).

{{% /tab %}}
Expand Down Expand Up @@ -359,6 +360,13 @@ Select from the **Levels** dropdown menu to filter the logs by severity level:
sudo journalctl --unit=viam-agent
```

{{% /tab %}}
{{% tab name="Command line on MacOS" %}}

```sh {class="command-line" data-prompt="$"}
less /var/log/viam-agent.log
```

{{% /tab %}}
{{% tab name="Event Viewer on Windows" %}}

Expand All @@ -381,5 +389,4 @@ You will find the `viam-agent` logs under **Windows Logs > Application** on the
| `-d`, `--debug` | Enable debug logging (on agent only). Can also be set with environment variable `VIAM_AGENT_DEBUG`. |
| `-w`, `--wait` | Update versions before starting. Can also be set with environment variable `VIAM_AGENT_WAIT_FOR_UPDATE`. |
| `-h`, `--help` | Show help message. |
| `--install` | Install systemd service. |
| `--dev-mode` | Allow running as non-root and non-service. Can also be set with environment variable `VIAM_AGENT_DEVMODE`. |
| `--install` | Install systemd/launchd service. |
61 changes: 59 additions & 2 deletions docs/manage/reference/viam-agent/manage-viam-agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,15 @@ type: docs
draft: false
images: ["/installation/thumbnails/manage.png"]
imageAlt: "Manage viam-agent"
description: "Control and manage the viam-agent systemd service."
description: "Control and manage the viam-agent system service."
date: "2024-08-16"
aliases:
- /installation/manage-viam-agent/
# updated: "" # When the content was last entirely checked
---

[`viam-agent`](/manage/reference/viam-agent/) is installed as a `systemd` service named `viam-agent`.
[`viam-agent`](/manage/reference/viam-agent/) is installed as a `systemd` service named
`viam-agent` on Linux, and as a `launchd` daemon named `system/com.viam.agent` on MacOS.

{{< tabs >}}
{{% tab name="Linux" %}}
Expand Down Expand Up @@ -72,6 +73,62 @@ If you remove the machine cloud credentials file you will not be able to connect
You can only restore this file if you have access to the machine configuration.
{{< /alert >}}

{{% /tab %}}
{{% tab name="MacOS" %}}

- To restart `viam-agent`:

{{< alert title="Alert" color="note" >}}
When you restart `viam-agent`, the agent will restart `viam-server` as well.
{{< /alert >}}

{{< tabs >}}
{{% tab name="Web UI" %}}

1. Navigate to your machine in [Viam](https://app.viam.com).
1. Click on the machine status indicator next to the machine name.
1. Click on the restart arrow symbol.
This will restart `viam-server` and `viam-agent`.

{{% /tab %}}
{{% tab name="Shell" %}}

```sh {class="command-line" data-prompt="$"}
sudo launchctl kickstart -k system/com.viam.agent
```

{{% /tab %}}
{{< /tabs >}}

- To start `viam-agent`:

```sh {class="command-line" data-prompt="$"}
sudo launchctl kickstart system/com.viam.agent
```

- To stop `viam-agent`:

{{< alert title="Alert" color="note" >}}
When you stop `viam-agent`, the agent will stop `viam-server` as well.
{{< /alert >}}

```sh {class="command-line" data-prompt="$"}
sudo launchctl kill SIGTERM system/com.viam.agent
```

- To completely uninstall `viam-agent` and `viam-server`, run the following command:

```sh {class="command-line" data-prompt="$"}
sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/uninstall.sh)"
```

This command uninstalls `viam-agent`, `viam-server`, and the machine cloud credentials file (<file>/etc/viam.json</file>).

{{< alert title="Caution" color="caution" >}}
If you remove the machine cloud credentials file you will not be able to connect to your machine.
You can only restore this file if you have access to the machine configuration.
{{< /alert >}}

{{% /tab %}}
{{% tab name="Windows native" %}}

Expand Down
Loading