System settings

Configure system-level settings for deployed machines. These settings are managed by viam-agent and configured in your machine’s JSON configuration under the agent config section. You can configure them directly on a machine or deploy them fleet-wide through a fragment.

Agent version control

Control which versions of viam-agent and viam-server run on each machine.

Manage version selection in the Viam app, not in your machine’s JSON configuration. In the machine settings card, open Settings and expand Software Updates:

  • Agent version: choose stable, a specific semver release such as 5.6.77, or a URL to a custom binary.
  • viam-server version: choose stable, a specific semver release, or a URL to a custom binary.

When you change a version, the cloud sends an update instruction to viam-agent on the machine. The agent downloads and installs the new version on its next check cycle. To control when the new version actually starts, configure a maintenance window. To verify the new version landed across the fleet, see verify a rollout across the fleet.

Agent advanced settings

In the machine settings card, open Settings and expand Advanced:

FieldTypeDefaultDescription
debugbooleanfalseEnable debug logging for viam-agent.
disable_network_configurationbooleanfalseDisable viam-agent’s network and hotspot management.
disable_system_configurationbooleanfalseDisable viam-agent’s system configuration management.
disable_viam_serverbooleanfalsePrevent viam-agent from starting viam-server. For development use.
viam_server_envobject{}Environment variables passed to viam-server and all modules.
viam_server_start_timeout_minutesinteger10Minutes to wait before restarting an unresponsive viam-server.
wait_for_update_checkbooleanfalseWait for a network connection and update check before starting viam-server.

Configure additional networks

Add WiFi or wired networks that the machine can connect to. Each network is a named entry with connection parameters.

In the machine settings card, open Settings and expand Known Networks. Click Add another network and configure:

FieldTypeDefaultDescription
typestring—Required. "wifi" or "wired".
ssidstring—WiFi network name. Only for WiFi networks.
pskstring—Network password or pre-shared key.
priorityinteger0Network selection priority. Higher values are preferred. Range: -999 to 999.
interfacestring—Network interface name (for example, "wlan0", "eth0").
ipv4_addressstring"auto"Static IPv4 address in CIDR notation (for example, "192.168.0.10/24").
ipv4_dnsarray[]DNS server addresses.
ipv4_gatewaystring—IPv4 gateway address.
ipv4_route_metricinteger0Route metric. Lower values are preferred. 0 defaults to 100 for wired, 600 for wireless.

Configure tunneling

Allow secure port forwarding from a local machine to a remote machine through Viam’s cloud connection. You must list allowed ports in the machine configuration.

{
  "network": {
    "traffic_tunnel_endpoints": [
      {
        "port": 8080,
        "connection_timeout": "30s"
      }
    ]
  }
}
FieldTypeDescription
portintegerThe port on the machine to expose for tunneling.
connection_timeoutstringTimeout for establishing the tunnel connection. Go duration format. Default: "10s".

To connect through the tunnel, use the CLI:

viam machines part tunnel --part=<part-id> --local-port=8080 --destination-port=8080

Disable TLS

By default, viam-server uses TLS for all connections. To disable TLS (for development or isolated networks only):

{
  "network": {
    "no_tls": true
  }
}

Configure bind address and port

By default, viam-server listens on localhost:8080. To change the bind address:

{
  "network": {
    "bind_address": "0.0.0.0:8081"
  }
}

Configure OS package updates

Control automatic operating system package updates on the machine.

In the machine settings card, open Settings and expand System. Set os_auto_upgrade_type:

ValueDescription
"all"Install all available OS package updates.
"security"Install security updates only.
"disable"Disable automatic OS updates.
"" (empty)Do not change the system’s current update settings. This is the default.

Automatic OS package updates require Debian Linux with one of these release codenames: Bullseye, Bookworm, or Trixie. On unsupported distributions, the agent logs a warning and the setting has no effect.

Configure OS log forwarding

Forward operating system logs from the machine to Viam’s cloud log viewer.

In the machine settings card, open Settings and expand System:

FieldTypeDefaultDescription
forward_system_logsstring""Which system logs to forward. Empty string disables forwarding.
logging_journald_runtime_max_use_megabytesinteger512Maximum temporary log storage in MB. Set to -1 to disable the limit.
logging_journald_system_max_use_megabytesinteger512Maximum persistent log storage in MB. Set to -1 to disable the limit.

Log forwarding filter syntax

The forward_system_logs field accepts:

  • "all": forward all system logs
  • A comma-separated list of service identifiers: forward only those services (for example, "kernel,NetworkManager,tailscaled")
  • Prefix a service with - to exclude it: "all,-gdm,-tailscaled" forwards everything except gdm and tailscaled

Verify settings changes

After updating system settings:

  1. Click Save on the CONFIGURE tab.
  2. Wait for the machine to sync the new configuration (up to one minute).
  3. Check the LOGS tab for any errors related to the changed settings.
  4. For network changes, verify the machine remains online in the fleet dashboard.

Related pages