Skip to main content

Installation

Install and configure the Foxglove Agent.

System requirements​

You will need:

  • HTTPS access to api.foxglove.dev (stable connection not required)
    • Currently resolves to IPs: 104.18.20.210 and 104.18.21.210
    • Port: 443 (HTTPS)
    • Used for: Device authentication, recording metadata upload, and control commands
  • A filesystem supporting fsnotify for recordings storage
  • For self-hosted deployments: network access to your Primary Site's inbox bucket
note

If configuring firewall rules, allowlist both IP addresses for api.foxglove.dev. The service uses DNS round-robin, so the Agent may connect to either IP.

Install the Agent​

The Foxglove Agent is available for AMD64 and ARM64 architectures in these forms:

  • A .deb package, for Debian-based Linux distributions
  • A statically-linked Linux executable
  • A Docker image

Download the latest foxglove-agent package for your architecture from the releases page. Install with dpkg:

# replace with downloaded filename
dpkg -i foxglove-agent_0.0.0_amd64.deb

Configure the Agent​

The following instructions explain how to set environment variables for the Agent. Where you set these depends on your installation method:

When using the .deb package, the Agent's environment is configured in /etc/foxglove/agent/envfile.

Here is a reference envfile to get you started:

# FOXGLOVE_DEVICE_TOKEN authenticates the agent to the API and should be
# obtained from the Foxglove devices UI. A particular Foxglove device should
# have at most a single associated agent.
FOXGLOVE_DEVICE_TOKEN=

# DEVICE_NAME must be specified when using a deviceless token. The agent will
# create a device with this name on first connection. Leave commented out
# when using a device-linked token.
#DEVICE_NAME=

# STORAGE_ROOT is the path from which the device agent will read your
# recordings. Recording paths will appear in Foxglove relative to this path.
STORAGE_ROOT=/srv/foxglove/agent/storage

# WATCH_INCLUDE_SUFFIXES is a comma-delimited list of file suffixes that should
# be treated as recordings. More granular filtering can be accomplished using
# regexes and exclusions.
WATCH_INCLUDE_SUFFIXES=.bag,.mcap
#WATCH_INCLUDE_REGEX=
#WATCH_EXCLUDE_SUFFIXES=
#WATCH_EXCLUDE_REGEX=

# WATCH_AUTO_IMPORT_PATTERN is the relative path from STORAGE_ROOT which the
# agent will automatically upload your recordings.
#WATCH_AUTO_IMPORT_PATTERN=

# FOXGLOVE_LOG_OUTPUT controls how logs are routed. When running the agent under
# systemd, this should typically be "journald". Other options are "json" or
# "text" to output JSON or human-readable logs to stderr.
FOXGLOVE_LOG_OUTPUT=journald

# VARDIR must be a read-writable path where the agent can store internal state.
VARDIR=/var/lib/foxglove/agent

# PRIMARY_SITE_MODE should be set to self-managed or hosted according to the
# deployment mode of the primary site to which the agent reports.
PRIMARY_SITE_MODE=hosted

Configure device token​

Set the FOXGLOVE_DEVICE_TOKEN environment variable to the secret device token generated previously. A device should have at most one Agent at any given time.

No additional configuration is required. The device identity is determined by the token.

Configure storage directory​

Configure the STORAGE_ROOT environment variable with the directory you want to monitor for newly recorded data files. This will serve as the Agent's data directory.

Configure the VARDIR environment variable with the directory you want to store the internal state of the Agent.

The Agent runs as the foxglove user and group under systemd. The foxglove user must have read and write access to the STORAGE_ROOT and VARDIR directories and their contents.

Depending on your system configuration, you may need to adjust directory ownership or group permissions to allow the foxglove user to access files created by other users (for example, your recording process). Common approaches include:

  • Adding the foxglove user to a shared group that has access to the storage directory 
    sudo usermod -a -G $GROUP foxglove
  • Adjusting directory ownership and permissions (for example, using chown and chmod)
note

If you make permission changes after starting the Agent service, restart the service for the permission changes to take effect.

sudo systemctl restart foxglove-agent

Configure recording filters​

By default, the Agent will attempt to read any file under STORAGE_ROOT as a recording, unless the file ends in .active or .json. For multipurpose storage directories, this will generate a large volume of repetitive log messages indicating that various files cannot be parsed as recordings.

Most users will want to override this behavior with WATCH_INCLUDE_SUFFIXES, which is a comma-delimited list of file suffixes that the Agent should treat as recordings. A setting of WATCH_INCLUDE_SUFFIXES=.bag,.mcap is a reasonable choice.

More granular filtering can be accomplished through the following variables:

  • WATCH_EXCLUDE_REGEX: A regex of paths the Agent should ignore
  • WATCH_EXCLUDE_SUFFIXES: A comma-delimited list of suffixes the Agent should ignore
  • WATCH_INCLUDE_REGEX: A regex of paths that the Agent should treat as recordings

If a combination of these variables are used, the Agent will treat a file as a recording if and only if it matches all of the include filters and none of the exclude filters.

The Agent can also be configured to auto-import data; see Automatically import recording files.

Upload settings​

Choose your upload configuration:

By default, your Organization will be configured with a Foxglove-hosted Primary Site. No additional configuration is required in this case.

Additional options​

In addition to the watch options above, Agent supports the following configuration options.

These can be set in your Agent's environment. The exact mechanism depends on how you install the Agent; see Installation. All are optional.

# SQLite database connection string.
# Format: must start with "sqlite://".
# Default: "controller.db" in the `$VARDIR` directory
DATABASE_CONNECTION_STRING=""

# Disable the prometheus metrics server.
# Format: "true" or "false"
DISABLE_PROMETHEUS=""

# Timeout for requests to the control plane.
# Format: a positive integer followed by a time unit ("ms", "s", "m", or "h").
FOXGLOVE_API_TIMEOUT="30s"

# Controls how logs are routed. For systemd, this should typically be "journald".
# Options: "journald", "json", or "text"
FOXGLOVE_LOG_OUTPUT="json"

# The batch size to use when deleting local recordings
# Format: a positive integer
GARBAGE_COLLECTION_BATCH_SIZE="1000"

# The interval between garbage collection passes (deleting local recordings)
# Format: a positive integer followed by a time unit ("ms", "s", "m", or "h").
GARBAGE_COLLECTION_INTERVAL="10s"

# Single-word prefix for Prometheus metrics
PROMETHEUS_METRICS_NAMESPACE=""

# Name of the subsystem for Prometheus metrics
PROMETHEUS_METRICS_SUBSYSTEM=""

# Port to listen on for the prometheus server.
# Format: a valid port number
PROMETHEUS_PORT="6001"

# The interval at which the Agent submits recording metadata to the control plane.
# Format: a positive integer followed by a time unit ("ms", "s", "m", or "h").
RECORDING_POLLING_INTERVAL="1s"

# The batch size when submitting recordings to the control plane.
# Format: a positive integer.
RECORDING_SUBMISSION_BATCH_SIZE="25"

# Storage directory for local recordings.
# All recordings must be strictly nested under this directory.
STORAGE_ROOT=""

# HTTP2 keepalive interval for recording uploads
# Format: a positive integer followed by a time unit ("ms", "s", "m", or "h").
UPLOAD_HTTP2_KEEP_ALIVE_INTERVAL="10s"

# HTTP2 keepalive timeout for recording uploads
# Format: a positive integer followed by a time unit ("ms", "s", "m", or "h").
UPLOAD_HTTP2_KEEP_ALIVE_TIMEOUT="30s"

# A read-writable directory where the Agent can store internal state.
VARDIR=""

Run the Agent​

The .deb package installs Agent as a systemd service.

  1. Restart the service and check its status:
sudo systemctl restart foxglove-agent
systemctl status foxglove-agent
  1. Enable automatic startup (optional):
sudo systemctl enable foxglove-agent
tip

Monitor the logs with journalctl for debugging:

journalctl -u foxglove-agent