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:

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​

When using the .deb package or standalone executable, 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.

When using the Agent Docker image, bind-mount your data directory to /storage inside the container. You do not need to configure STORAGE_ROOT .

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