# viam-server reference

The `viam-server` executable runs on a computer and manages hardware, software, and data for a machine. `viam-server` is built from the open-source [Robot Development Kit (RDK)](https://github.com/viamrobotics/rdk). If you are working with microcontrollers, [`viam-micro-server`](https://docs.viam.com/reference/device-setup/setup-micro/) is a lightweight version of `viam-server` which can run on resource-limited embedded systems that cannot run the fully-featured `viam-server`.

To use Viam with a machine, you create a configuration specifying which hardware and software the machine consists of. `viam-server` then manages and runs the drivers for the configured resources.

Overall, `viam-server` manages:

- [Communication](https://docs.viam.com/reference/viam-server/#communication)
- [Start-up](https://docs.viam.com/reference/viam-server/#start-up)
- [Reconfiguration](https://docs.viam.com/reference/viam-server/#reconfiguration)
- [Maintenance windows](https://docs.viam.com/reference/viam-server/#maintenance-window)
- [Shutdown](https://docs.viam.com/reference/viam-server/#shutdown)
- [Logging](https://docs.viam.com/reference/viam-server/#logging)

## Communication

`viam-server` handles all gRPC and WebRTC communication for connecting machines to the cloud or for connecting to other parts of your machine.

All communication happens securely over HTTPS using secret tokens that are in the machine’s config.

## Lifecycle

### Start-up

The machine setup steps copy your machine’s credentials to your machine. When you turn on your machine, `viam-server` starts up and uses the provided credentials to fetch its configuration from Viam.

`viam-server` ensures that any configured modules, built-in resources and modular resources are loaded on startup. `viam-server` handles [dependency](https://docs.viam.com/build-modules/dependencies/) management between resources.

After start-up, `viam-server` manages:

- the connections to hardware,
- the running services, and
- the modules that provide the modular resources.

### Reconfiguration

Once the machine has a configuration, it caches it locally (in a file at ~/.viam/cached_cloud_config_<PART-ID>.json) and can use the config for up to 60 days. Since the configuration is cached locally, your machine does not need to stay connected to Viam after it has obtained its configuration file.

If it is online, the machine automatically checks for new configurations every 15 seconds. When you or your collaborators change the configuration of a machine, `viam-server` automatically synchronizes the configuration to your machine and updates the running resources.

Reconfiguration of individual resources happens concurrently if there are no configured dependencies for any resources. If there are configured dependencies, resources are reconfigured in groups.

You can see configuration changes made by yourself or by your collaborators by selecting **History** on the right side of your machine part’s card on the **CONFIGURE** tab. You can also revert to an earlier configuration from the History tab.

If you want to force a reconfiguration of a resource, you can click the **Disable** button in the resource menu, save, and then re-enable the resource.

Alternatively, if you are having issues with a module, try the **Restart module** button in the module menu.

### Maintenance window

There are a few updates that may make your machine temporarily unavailable:

- [`viam-agent` updating itself](https://docs.viam.com/reference/viam-agent/#version-control)
- [`viam-agent` updating `viam-server`](https://docs.viam.com/reference/viam-agent/#version-control)
- configuration updates

To avoid performing these updates until your machine is ready for maintenance, you can define a maintenance window. A maintenance window consists of one or multiple conditions that determine if maintenance is currently allowed. To configure a maintenance window, you need to create a sensor that returns true when your maintenance conditions are met and false otherwise.

To configure a maintenance window, click the **+** icon next to your machine part in the left-hand menu of the **CONFIGURE** tab and select **Maintenance window**.

In the new panel, specify the name of the sensor and the key for the value to be used to determine when maintenance is allowed.

To configure a maintenance window, add the following configuration to your machine’s JSON configuration:

```json
// components: [ ... ],
// services: [ ... ],
maintenance : {
   "sensor_name" : string,
   "maintenance_allowed_key" : string
}
```

| Attribute | Type | Required? | Description |
| --- | --- | --- | --- |
| `sensor_name` | string | **Required** | The full name of the sensor that provides the information if it is safe to update a machine’s configuration. For example `rdk:component:sensor/sensor1`. |
| `maintenance_allowed_key` | string | **Required** | The key of the key value pair for the reading returned by the sensor. |

### Shutdown

During machine shutdown, `viam-server` handles modular resource instances similarly to built-in resource instances - it signals them for shutdown in topological (dependency) order.

## Logging

Log messages appear under the **LOGS** tab for a machine.

The default log level for `viam-server` and any running resources is `"Info"`. Logs are stored for 30 days before they are deleted.

If you need more logs for an individual resource, click **Enable debug logs** in the **…** menu on the resource.

To set other log levels for individual resources, add the `log_configuration` option to the resource’s JSON configuration:

```json
"log_configuration": {
    "level": "Debug"
},
"attributes": { ... }
```

For modular resources, you must instead set the `log_level` attribute on the module itself:

```json

```

Alternatively, you can configure logs for all machine resources, inside your machine config. To specify the log level for a specific resource, add the `log` field to your machine config:

For example:

```json
"components": [ ... ]
"log": [\
    {\
    "pattern": "rdk.components.arm",\
    "level": "debug",\
    }, {\
    "pattern": "rdk.services.*",\
    "level": "debug",\
    }, {\
    "pattern": "<module-name>",\
    "level": "debug",\
    }\
]
```

| Attribute | Description |
| --- | --- |
| `pattern` | A regular expression (regex) pattern matching one or more resources. |
| `level` | The log level: `"debug"`, `"info"`, `"warn"`, or `"error"`. |

Patterns are processed from top to bottom. If multiple patterns apply, the last pattern to be processed will apply. If log configurations are applied at a resource level using the `log_configuration` field, these take precedence over log levels applied in the `log` field of the machine configuration.

### Disable log deduplication

By default, `viam-server` deduplicates log messages that are deemed noisy. A log is deemed noisy after the same message is logged more than 3 times within one minute.

Log deduplication is automatically disabled when debug logging is active, whether you enable logging with `"debug": true` in your machine’s configuration or with the `-debug` command-line flag. You do not need to set `disable_log_deduplication` separately when running in debug mode.

To disable log deduplication without enabling debug mode, set `disable_log_deduplication` in your machine’s configuration:

```json
"disable_log_deduplication": true
```

### Delete machine logs

You cannot delete machine logs. If your machine has generated a large amount of logs and you are concerned about the cost, you can:

1. Copy the machine’s configuration to a new machine.
2. Delete the old machine.

If you delete a machine you will not be charged for the remainder of the 30 days until logs from that machine are deleted.

### Debugging

You can enable debug level logs in two ways:

- Start `viam-server` with the `-debug` option.
- Add `"debug": true` to the machine’s configuration:

```json
{
    "debug": true,
    "components": [{ ... }]
}
```

Enabling debug level logs will take precedence over all logging configuration set using the `log` field on a machine or the `log_configuration` field on a resource.

## Core options

| Option | Description |
| --- | --- |
| `-allow-insecure-creds` | Allow connections to send credentials over plaintext. |
| `-config <filename>` | The machine configuration file containing machine cloud credentials or a full configuration. |
| `-cpuprofile string` | Write CPU profile to file. |
| `-debug` | Enable debug level logs. |
| `-disable-mdns` | Disable server discovery through multicast DNS. |
| `-dump-resources <filepath>` | Dump all resource registrations as JSON to the provided file path. |
| `-ftdc` | Enable fulltime data capture for diagnostics. Default: `true`. |
| `-log-file <filename>` | Write logs to a file with log rotation. |
| `-network-check` | Only runs normal network checks. |
| `-no-tls` | Starts an insecure HTTP server without TLS certificates even if one exists. |
| `-output-telemetry` | Print out telemetry data (metrics and spans). |
| `-reveal-sensitive-config-diffs` | Show config diffs. |
| `-shareddir <directory-name>` | The location of the static web assets. |
| `-untrusted-env` | Disable processes and shell from running in an untrusted environment. |
| `-version` | Print version. |
| `-webprofile` | Include profiler in HTTP server. |
| `-webrtc` | Force WebRTC connections instead of direct connections. Default: `true`. |

## Environment variables

You can set the following environment variables to configure `viam-server` behavior without command-line flags:

| Variable | Description |
| --- | --- |
| `VIAM_HOME` | Path to the directory where `viam-server` stores cached files and module data. Defaults to `~/.viam`. |
| `VIAM_CONFIG_READ_TIMEOUT` | Override the default 15-second timeout for reading the machine configuration, for example `30s` or `1m`. |
| `VIAM_RESOURCE_REQUESTS_LIMIT` | Override the default limit of 100 concurrent gRPC requests allowed per resource. |
| `VIAM_MODULE_STARTUP_TIMEOUT` | Override the default 5-minute module startup timeout, for example `10m` or `30s`. |
| `VIAM_RESOURCE_CONFIGURATION_TIMEOUT` | Override the default 2-minute per-resource configuration timeout. |
| `VIAM_LOGFILE` | Path to a log file. `viam-server` writes logs to this file in addition to standard output. This differs from the `-log-file` flag, which writes to the file instead of standard output. |
| `VIAM_NO_WINDOWS_EVENT_LOGGER` | If set to any value, disables writing logs to the Windows Event Logger and Event Tracing for Windows (ETW). Only relevant on Windows. |

## Install `viam-server` without the web UI

#### Tip

The recommended way to install `viam-server` and connect your machine to Viam is covered in the [Set up a machine](https://docs.viam.com/set-up-a-machine/).

If you need to install `viam-server` without the web UI, you can run the following commands.

- [Linux (Aarch64)](https://docs.viam.com/reference/viam-server/#tabset-referenceviam-server-4-0)
- [Linux (x86_64)](https://docs.viam.com/reference/viam-server/#tabset-referenceviam-server-4-1)
- [macOS](https://docs.viam.com/reference/viam-server/#tabset-referenceviam-server-4-2)
- [Windows Subsystem for Linux (WSL)](https://docs.viam.com/reference/viam-server/#tabset-referenceviam-server-4-3)
- [Windows native](https://docs.viam.com/reference/viam-server/#tabset-referenceviam-server-4-4)

- [Install manually](https://docs.viam.com/reference/viam-server/#tabset-referenceviam-server-2-0)
- [Install using viam-agent](https://docs.viam.com/reference/viam-server/#tabset-referenceviam-server-2-1)

The `viam-server` binary is installed at /usr/local/bin/viam-server.

```sh
sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)"
```

The `viam-agent` and `viam-server` binaries are installed at /opt/viam/bin/viam-server.

### Install a specific version of `viam-server`

In some cases, you may need to install an older version of `viam-server`.

For Linux systems, the recommended approach to install an older version is to build from source:

```sh
# Clone the RDK repository
git clone https://github.com/viamrobotics/rdk.git

# Change to the RDK directory
cd rdk

# Check out a specific version tag (replace v0.46.0 with your desired version)
git checkout v0.46.0

# Build the server
make server

# The binary will be available in the bin directory for your architecture
cd bin/Linux-amd64  # or Linux-arm64 for ARM-based systems
```

You can then run the server directly:

```sh
sudo ./viam-server -config /path/to/your/config.json
```

There are two approaches to installing an older version of `viam-server` on macOS:

### Option 1: Build from source

The most reliable way to install a specific version of `viam-server` is to clone the RDK repository at a specific tag and build it yourself:

```sh
# Clone the RDK repository
git clone https://github.com/viamrobotics/rdk.git

# Change to the RDK directory
cd rdk

# Check out a specific version tag (replace v0.46.0 with your desired version)
git checkout v0.46.0

# Build the server
make server

# The binary will be available in the bin directory for your architecture
cd bin/Darwin-arm64  # Use the folder matching your architecture
```

You can then run the server directly:

```sh
./viam-server -config /path/to/your/config.json
```

### Option 2: Use an older version of the Homebrew tap

If you’ve already installed `viam-server` with Homebrew, you can try checking out an older version of the Viam Homebrew tap:

```sh
# Navigate to the Homebrew tap directory
cd /opt/homebrew/Library/Taps/viamrobotics/homebrew-brews/

# Check out an older version of the tap
git checkout <older-commit-hash>

# Reinstall viam-server
brew reinstall viam-server
```

Note that this method may not work for versions that are too old, as Homebrew doesn’t officially support installing older versions of dependencies. If the version you need is significantly older, building from source (Option 1) is recommended.