From 0da70a2b4aeda30c843a46bb07257ed2576667dd Mon Sep 17 00:00:00 2001 From: Benjamin Rewis Date: Thu, 12 Mar 2026 12:37:19 -0400 Subject: [PATCH 1/4] Correct launchctl commands for MacOS agent management --- .../reference/viam-agent/manage-viam-agent.md | 33 ++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/manage/reference/viam-agent/manage-viam-agent.md b/docs/manage/reference/viam-agent/manage-viam-agent.md index 0d4cb6817a..067277f806 100644 --- a/docs/manage/reference/viam-agent/manage-viam-agent.md +++ b/docs/manage/reference/viam-agent/manage-viam-agent.md @@ -106,14 +106,45 @@ You can only restore this file if you have access to the machine configuration. sudo launchctl kickstart system/com.viam.agent ``` + If the service fails to start, make sure it is bootstrapped. The following command will + print an error message if the service is NOT boostrapped. + + ```sh {class="command-line" data-prompt="$"} + sudo launchctl print system/com.viam.agent + ``` + + The following command will bootstrap the service. + + ```sh {class="command-line" data-prompt="$"} + sudo launchctl bootstrap system /Library/LaunchDaemons/com.viam.agent.plist + ``` + + If the service STILL fails to start, ensure that it is enabled. The following command + will enable the service. + + ```sh {class="command-line" data-prompt="$"} + sudo launchctl enable 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 >}} + `sudo launchctl kill` and `sudo launchctl stop` will NOT fully stop `viam-agent`, as + launchd will automatically resurrect it. You can use the following to "boot out" the + service and fully stop it. + + ```sh {class="command-line" data-prompt="$"} + sudo launchctl bootout system/com.viam.agent + ``` + + If you would like to start `viam-agent` again after this command, you will need to + bootstrap it again. + ```sh {class="command-line" data-prompt="$"} - sudo launchctl kill SIGTERM system/com.viam.agent + sudo launchctl bootstrap system /Library/LaunchDaemons/com.viam.agent.plist ``` - To completely uninstall `viam-agent` and `viam-server`, run the following command: From 0569a68801294d1ed960404571aa47ae25da9aad Mon Sep 17 00:00:00 2001 From: Benjamin Rewis Date: Thu, 12 Mar 2026 12:39:58 -0400 Subject: [PATCH 2/4] Fix typo --- docs/manage/reference/viam-agent/manage-viam-agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manage/reference/viam-agent/manage-viam-agent.md b/docs/manage/reference/viam-agent/manage-viam-agent.md index 067277f806..0b1cb6fa1d 100644 --- a/docs/manage/reference/viam-agent/manage-viam-agent.md +++ b/docs/manage/reference/viam-agent/manage-viam-agent.md @@ -107,7 +107,7 @@ You can only restore this file if you have access to the machine configuration. ``` If the service fails to start, make sure it is bootstrapped. The following command will - print an error message if the service is NOT boostrapped. + print an error message if the service is NOT bootstrapped. ```sh {class="command-line" data-prompt="$"} sudo launchctl print system/com.viam.agent From 5e6c2116f57103153d49ffa06f03fd1c1f8fe216 Mon Sep 17 00:00:00 2001 From: Benjamin Rewis Date: Thu, 12 Mar 2026 13:16:12 -0400 Subject: [PATCH 3/4] Remove references to viam-server Homebrew service --- docs/operate/reference/viam-server/_index.md | 14 +++------- .../viam-server/manage-viam-server.md | 26 +++---------------- 2 files changed, 6 insertions(+), 34 deletions(-) diff --git a/docs/operate/reference/viam-server/_index.md b/docs/operate/reference/viam-server/_index.md index f5f71ae54c..2429214255 100644 --- a/docs/operate/reference/viam-server/_index.md +++ b/docs/operate/reference/viam-server/_index.md @@ -358,17 +358,9 @@ brew tap viamrobotics/brews && brew install viam-server The `viam-server` binary is installed at /opt/homebrew/bin/viam-server. -You can optionally run `viam-server` as a background service with Homebrew: - -1. Place your machine configuration at /opt/homebrew/etc/viam.json. - -1. Start the service with: - - ```sh {class="command-line" data-prompt="$" data-output="5-10"} - brew services start viam-server - ``` - -For more information about brew services, run `brew services --help`. +The brew installation of `viam-server` CANNOT be run as a system service in the +background. If you would like to run `viam-server` in the background, install +[`viam-agent`](/manage/reference/viam-agent/) instead. {{% /tab %}} {{% tab name="Windows Subsystem for Linux (WSL)" %}} diff --git a/docs/operate/reference/viam-server/manage-viam-server.md b/docs/operate/reference/viam-server/manage-viam-server.md index 747e2a91ed..8e19d6dc16 100644 --- a/docs/operate/reference/viam-server/manage-viam-server.md +++ b/docs/operate/reference/viam-server/manage-viam-server.md @@ -127,29 +127,9 @@ Type **Ctrl + C** on your keyboard within the terminal session where you are run ### Run as a system service -Installing `viam-server` as a system service is not recommended for most use cases on macOS. -However, if you are looking to create a machine that runs on macOS and you want it to run `viam-server` automatically when your macOS system boots, then you will need to run `viam-server` as a service. - -Once you have [installed `viam-server`](/operate/install/setup/) on your macOS computer, use the following commands to control the service. -These commands require that you store your machine cloud credentials file at /opt/homebrew/etc/viam.json. - -#### Start - -```sh {class="command-line" data-prompt="$"} -brew services start viam-server -``` - -#### Stop - -```sh {class="command-line" data-prompt="$"} -brew services stop viam-server -``` - -#### Restart - -```sh {class="command-line" data-prompt="$"} -brew services restart viam-server -``` +The brew installation of `viam-server` CANNOT be run as a system service in the +background. If you would like to run `viam-server` in the background, install +[`viam-agent`](/manage/reference/viam-agent/) instead. {{% /tab %}} {{< /tabs >}} From 4f6eaa0d0ea6d40742fdab3fcae5868be8e03043 Mon Sep 17 00:00:00 2001 From: Benjamin Rewis Date: Thu, 12 Mar 2026 13:21:43 -0400 Subject: [PATCH 4/4] Remove reference to brew log location --- docs/operate/reference/viam-server/manage-viam-server.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/operate/reference/viam-server/manage-viam-server.md b/docs/operate/reference/viam-server/manage-viam-server.md index 8e19d6dc16..0439fc21b1 100644 --- a/docs/operate/reference/viam-server/manage-viam-server.md +++ b/docs/operate/reference/viam-server/manage-viam-server.md @@ -306,12 +306,6 @@ grep viam-server /var/log/syslog When running `viam-server` on macOS, log messages are written to standard out (`stdout`) in the same terminal session you started `viam-server` in. -You can also access the local `viam-server` log file using the following command: - -```sh {class="command-line" data-prompt="$"} -cat $(brew --prefix)/var/log/viam.log -``` - {{% /tab %}} {{< /tabs >}}