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)
  • A filesystem supporting fsnotify for recordings storage
  • For self-hosted deployments: network access to your Primary Site's inbox bucket

Create a device and token​

  1. Go to the Devices page to create or select a device
  2. Have an admin generate a secret token from the device's "Device Tokens" tab
tip

Admins can also create device tokens via API. Generate an API key with deviceToken capabilities from the API key settings page and use it to create device tokens.

note

Each Agent installation requires its own unique device and device token. Multi-compute robots sharing a single device aren't supported.

Install the Agent​

Foxglove Agent is available for installation in these forms:

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

Debian packages and executables can be downloaded from the releases page for AMD64 and ARM64 architectures. To upgrade the package, check the releases page for newer release versions to download.

Using Docker​

A multi-platform Docker image is available at us-central1-docker.pkg.dev/foxglove-images/images/agent.

The Agent needs a writable directory to store its own persistent state. This must be mounted inside the container at /index. You can use a Docker Volume to manage this state:

docker volume create foxglove-agent-index-storage
docker run \
  --mount type=volume,src=foxglove-agent-index-storage,dst=/index \
  --mount type=bind,src=/path/to/recording/storage,dst=/storage \
  --env-file your-agent-config.env \
    us-central1-docker.pkg.dev/foxglove-images/images/agent:0.0.0 # replace with a valid release version number

From the Debian package​

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 identity​

The agent is associated with a device using the FOXGLOVE_DEVICE_TOKEN environment variable, which should be set to the secret device token generated above. A device should have at most one agent at any given time.

Changing device identity​

If an agent is reconfigured with a new device token which refers to a new device, the agent will fail to initialize with an error message: conflicting local device identity: {device-name} ({device-id}). This is a safeguard to prevent misconfiguration. If the change in identity is intentional, you will need to delete the agent's local database ($VARDIR/controller.db).

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.

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.

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