Set up a machine: add viam-agent and viam-server explainer; rename section (#4972)

shannonbradshaw · claude · web-flow · commit b6a3187da376 · 2026-04-17T19:12:05.000-04:00
Co-authored-by: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/cli/configure-machines.md b/docs/cli/configure-machines.md
@@ -53,7 +53,7 @@ viam machines create --name=my-machine --location=<location-id>
 ```
 
 This creates the machine in the Viam app.
-The machine is not connected to any hardware until you [install `viam-server`](/foundation/) on a device and configure it with this machine's credentials.
+The machine is not connected to any hardware until you [install `viam-server`](/set-up-a-machine/) on a device and configure it with this machine's credentials.
 
 On success, the CLI prints the new machine's ID:
 
@@ -213,7 +213,7 @@ viam machines part restart --part=<part-id>
 
 ## Related pages
 
-- [Get started](/foundation/) for setting up your first machine
+- [Get started](/set-up-a-machine/) for setting up your first machine
 - [Configure hardware](/hardware/) for component configuration with the Viam app
 - [Manage your fleet with the CLI](/cli/manage-your-fleet/) for monitoring and remote access
 - [CLI reference](/cli/) for the complete `machines` command reference
diff --git a/docs/data/data-management-tutorial.md b/docs/data/data-management-tutorial.md
@@ -16,7 +16,7 @@ In this tutorial, you will set up a complete data pipeline: capture sensor data
 
 **What you need:**
 
-- A machine connected to the Viam app (if you don't have one yet, follow [Set up a machine](/foundation/))
+- A machine connected to the Viam app (if you don't have one yet, follow [Set up a machine](/set-up-a-machine/))
 - Python 3 installed on your laptop or desktop (for the final step)
 
 We will use a fake sensor so this tutorial works without any physical hardware.
diff --git a/docs/data/reference.md b/docs/data/reference.md
@@ -339,6 +339,6 @@ Control deletion behavior with the `delete_every_nth_when_disk_full` attribute.
 
 ### Micro-RDK
 
-The [micro-RDK](/foundation/setup-micro/) (for ESP32 and similar microcontrollers) supports data capture with a smaller set of resources than `viam-server`. See the **Micro-RDK** tab in the [supported resources table](#supported-resources) for the specific methods available.
+The [micro-RDK](/set-up-a-machine/setup-micro/) (for ESP32 and similar microcontrollers) supports data capture with a smaller set of resources than `viam-server`. See the **Micro-RDK** tab in the [supported resources table](#supported-resources) for the specific methods available.
 
 On micro-RDK devices, captured data is stored in the ESP32's flash memory until it is uploaded to the cloud. If the machine restarts before all data is synced, unsynced data since the last sync point is lost.
diff --git a/docs/fleet/overview.md b/docs/fleet/overview.md
@@ -54,7 +54,7 @@ Modules and ML models are stored as versioned packages in the Viam registry. Whe
 
 ## How fleet deployment fits with other sections
 
-- **[Get started](/foundation/)** covers setting up a single machine. Start there if you haven't created your first machine yet.
+- **[Get started](/set-up-a-machine/)** covers setting up a single machine. Start there if you haven't created your first machine yet.
 - **[Configure hardware](/hardware/)** covers adding components and services to a machine. Use fragments to templatize those configurations for your fleet.
 - **[Build and deploy modules](/build-modules/)** covers writing and uploading modules. This section covers deploying those modules to machines.
 - **[Train ML models](/train/)** covers training models. This section covers deploying trained models fleet-wide.
diff --git a/docs/fleet/provision-devices.md b/docs/fleet/provision-devices.md
@@ -33,7 +33,7 @@ If you are setting up a small number of machines manually, you can skip provisio
 ## Prerequisites
 
 - A [fragment](/fleet/reuse-configuration/) with the configuration your machines should use. Note the fragment ID.
-- A device with a supported Linux OS. See the [platform requirements](/foundation/) for supported platforms.
+- A device with a supported Linux OS. See the [platform requirements](/set-up-a-machine/) for supported platforms.
 
 ## 1. Create the defaults file
 
diff --git a/docs/fleet/reuse-configuration.md b/docs/fleet/reuse-configuration.md
@@ -14,7 +14,7 @@ As a fleet grows, machines tend to drift into unique, undocumented configuration
 
 ## Prerequisites
 
-- A Viam account with an organization. See [get started](/foundation/) if you have not set up your first machine yet.
+- A Viam account with an organization. See [get started](/set-up-a-machine/) if you have not set up your first machine yet.
 - At least one machine connected to Viam.
 
 ## When to use fragments
diff --git a/docs/hardware/multi-machine/add-a-sub-part.md b/docs/hardware/multi-machine/add-a-sub-part.md
@@ -15,7 +15,7 @@ If you have not yet decided between a sub-part and a remote part, start at the [
 
 ## Before you start
 
-- The main part is set up and online. If not, work through [Set up a machine](/foundation/) first.
+- The main part is set up and online. If not, work through [Set up a machine](/set-up-a-machine/) first.
 - You have the second computer ready: powered on, on the network, and able to reach the public internet. `viam-server` does not have to be installed yet.
 
 ## 1. Create the sub-part entry
@@ -37,7 +37,7 @@ The sub-part now exists in the configuration. It is not yet running.
 3. Follow the platform and install method selections, then run the install command on the second computer.
 
 The install flow is the same one used for the main part.
-See [Set up a machine](/foundation/) for details on platform choices and troubleshooting.
+See [Set up a machine](/set-up-a-machine/) for details on platform choices and troubleshooting.
 
 ## 3. Confirm the sub-part is online
 
diff --git a/docs/monitor/overview.md b/docs/monitor/overview.md
@@ -67,7 +67,7 @@ This section covers tools for monitoring, operating, and debugging machines that
 
 | If you need to...                              | See                                     |
 | ---------------------------------------------- | --------------------------------------- |
-| Set up a machine for the first time            | [Get started](/foundation/)             |
+| Set up a machine for the first time            | [Get started](/set-up-a-machine/)       |
 | Configure components and services              | [Configure hardware](/hardware/)        |
 | Capture and sync data from sensors             | [Manage data](/data/)                   |
 | Train and deploy ML models                     | [Train ML models](/train/)              |
diff --git a/docs/reference/components/board/micro-rdk/esp32.md b/docs/reference/components/board/micro-rdk/esp32.md
@@ -18,7 +18,7 @@ micrordk_component: true
 
 {{% alert title="REQUIREMENTS" color="caution" %}}
 
-Follow the [setup guide](/foundation/) to install and run `viam-micro-server` before configuring an `esp32` board.
+Follow the [setup guide](/set-up-a-machine/) to install and run `viam-micro-server` before configuring an `esp32` board.
 
 Viam recommends purchasing the ESP32 with a development board.
 The following ESP32 microcontrollers are supported:
diff --git a/docs/set-up-a-machine/_index.md b/docs/set-up-a-machine/_index.md
@@ -0,0 +1,11 @@
+---
+linkTitle: "Set up a machine"
+title: "Set up a machine"
+weight: 30
+layout: "docs"
+type: "docs"
+no_list: true
+manualLink: "/set-up-a-machine/overview/"
+description: "Create a machine in the Viam app and install Viam on your compute machine."
+date: "2025-01-30"
+---
diff --git a/docs/set-up-a-machine/overview.md b/docs/set-up-a-machine/overview.md
@@ -1,14 +1,14 @@
 ---
 linkTitle: "Set up a machine"
 title: "Set up a machine"
-weight: 30
+weight: 1
 layout: "docs"
 type: "docs"
 description: "Create a machine in the Viam app and install Viam on your compute machine."
 date: "2025-01-30"
 aliases:
-  - /build/foundation/
   - /foundation/
+  - /build/foundation/
   - /foundation/initialize-a-viam-machine/
   - /build/foundation/initialize-a-viam-machine/
   - /operate/install/
diff --git a/docs/set-up-a-machine/setup-micro/_index.md b/docs/set-up-a-machine/setup-micro/_index.md
@@ -6,6 +6,7 @@ layout: "docs"
 type: "docs"
 description: "Set up micro-controller."
 aliases:
+  - /foundation/setup-micro/
   - /operate/install/setup-micro/
   - /operate/get-started/other-hardware/micro-module/
 _build:
diff --git a/docs/set-up-a-machine/setup-micro/micro-module.md b/docs/set-up-a-machine/setup-micro/micro-module.md
@@ -5,6 +5,8 @@ type: "docs"
 weight: 50
 description: "Create your own modules for use with an Espressif ESP32 microcontroller."
 date: "2024-12-11"
+aliases:
+  - /foundation/setup-micro/micro-module/
 _build:
   list: never
 ---
diff --git a/docs/set-up-a-machine/setup-micro/micro-troubleshooting.md b/docs/set-up-a-machine/setup-micro/micro-troubleshooting.md
@@ -4,6 +4,8 @@ linkTitle: "Micro-RDK troubleshooting"
 weight: 100
 type: docs
 description: "Troubleshooting tips and best practices for installing and using viam-micro-server or other Micro-RDK-based firmware on a microcontroller."
+aliases:
+  - /foundation/setup-micro/micro-troubleshooting/
 _build:
   list: never
 ---
diff --git a/docs/set-up-a-machine/viam-agent-and-server.md b/docs/set-up-a-machine/viam-agent-and-server.md
@@ -0,0 +1,86 @@
+---
+linkTitle: "viam-agent and viam-server"
+title: "viam-agent and viam-server"
+weight: 10
+layout: "docs"
+type: "docs"
+description: "The two programs that run on every Viam machine: what each does, how they relate, and how they run modules."
+date: "2026-04-17"
+---
+
+When you install Viam on a computer, two programs land on the machine: `viam-agent` and `viam-server`. They have distinct jobs.
+
+## viam-server
+
+`viam-server` is the runtime that gives your machine its behavior.
+It reads the machine's configuration, loads each component and service, and exposes them through APIs so your code, the Viam app, and other machines can control them.
+`viam-server` listens on gRPC, HTTP, and (when signaled) WebRTC. That is how an SDK connects to the machine.
+
+Most of what people mean by "Viam running on my robot" is `viam-server`. When you write SDK code that calls `Motor.from_robot(...)`, that connection terminates at `viam-server` on the machine.
+
+## viam-agent
+
+`viam-agent` is a process manager that sits above `viam-server`.
+It runs as a system service (systemd on Linux, launchd on macOS) and manages three subsystems:
+
+- **viam-server**: launches it, restarts it on unexpected exit, and applies version updates from the cloud.
+- **networking**: helps with connectivity when the machine boots, including Wi-Fi provisioning on supported platforms.
+- **syscfg**: applies machine-level system configuration.
+
+`viam-agent` is the always-on layer. If the machine reboots, `viam-agent` comes up first and starts `viam-server`. If `viam-server` crashes, `viam-agent` restarts it.
+
+## How they work together
+
+At a typical startup, the OS starts the systemd or launchd service, which runs `viam-agent`. `viam-agent` starts `viam-server` as a subprocess, monitors it, and handles restarts. If a new `viam-server` version is released and your cloud config permits it, `viam-agent` downloads and installs the update, then restarts `viam-server` on the new version.
+
+You interact with `viam-server` through the Viam app, the CLI, and SDKs. You do not typically interact with `viam-agent` directly unless you are troubleshooting install or version-update issues.
+
+## How viam-server runs modules
+
+A **module** is a code package that provides one or more models (implementations of Viam component or service APIs for specific hardware or software).
+Most hardware support comes from modules in the [Viam registry](https://app.viam.com/registry), not from built-ins.
+
+### Pulling and caching
+
+When `viam-server` receives a config from the cloud, it looks at the `modules` block.
+For each registry module, `viam-server` asks the Viam package service where to download the module, fetches it over HTTP, and caches it locally under the machine's packages directory.
+
+Subsequent config syncs check which packages have changed.
+Unchanged modules are not re-downloaded; `viam-server` reuses the local copy.
+This is what lets a machine reboot or reconnect after a network outage without pulling everything again.
+
+### Launching modules as subprocesses
+
+Each module runs as a separate subprocess, not as library code inside `viam-server`.
+`viam-server` opens a UNIX domain socket in a temporary directory, passes the socket path to the module when it launches, and the module connects back over gRPC on that socket.
+The parent-child relationship keeps module crashes from bringing down `viam-server`.
+
+### Restarting a module
+
+If a module exits unexpectedly, `viam-server` restarts it automatically.
+If you change the module's config (version, attributes, or anything else that changes the module's identity), `viam-server` stops the old process and starts a new one.
+You can also trigger a restart manually from the app or through the SDK's `RestartModule` call, useful when you have pushed new module code and want to pick it up without touching anything else.
+
+### Offline operation
+
+Once modules are cached, the machine can keep running if the internet drops:
+
+- `viam-server` continues to serve requests locally.
+- Modules keep talking to `viam-server` over the local UNIX sockets.
+- Components and services configured on the machine continue to work.
+
+Cloud-dependent operations pause during an outage.
+Data sync to Viam Cloud pauses, remote resources on other machines become unreachable, and config changes pushed from the cloud do not reach the machine until it reconnects.
+
+### Local inter-module communication
+
+Modules do not talk to each other directly.
+When one module depends on another module's resource (for example, a custom camera module that depends on a built-in board for GPIO), the dependency is resolved by name and the request flows through `viam-server`.
+From the module's perspective it calls a gRPC client; under the hood, that client connects to `viam-server`, which routes the call to the resource's actual owner.
+
+This keeps the architecture simple. There is no N-by-N mesh of module sockets, and you can replace any module without rewiring the others.
+
+## Related
+
+- [What is a module?](/build-modules/overview/): the module side of this picture, including module anatomy and how to write one.
+- [What is Viam?](/what-is-viam/): where `viam-agent` and `viam-server` sit in the broader platform architecture.
