You can use environment variables to control Formant agent behavior. The agent reads its environment once, when the formant-agent process starts. Editing a file without restarting the agent does nothing.

This guide outlines where to set environment variables, the list of available variables, their default values, and their usage.

Where to set environment variables

Native (Debian package) installations

Add export lines to the formant user's .bashrc:

/var/lib/formant/.bashrc

The formant user which runs the formant-agent process sources /var/lib/formant/.bashrc before running the agent process. For example:

echo 'export FORMANT_UPLOAD_RATE_LIMIT_KBPS=750' | sudo tee -a /var/lib/formant/.bashrc
sudo systemctl restart formant-agent

Docker installations

The Docker agent reads the same variables. There are two ways to set them:

1. Container environment. Pass -e NAME=value to docker run, or to the installer through --extra-args. Container environment is fixed when the container is created, so to change a value later, re-run the installer without the provisioning token and with the new --extra-args; it recreates the container and keeps your credentials.

   Shell

   bash <(wget -qO - https://app.formant.io/install-agent.sh) --method docker --ros 1 \
       --extra-args "-e FORMANT_UPLOAD_RATE_LIMIT_KBPS=750"

2. The mounted .bashrc. The installer mounts the host's /var/lib/formant into the container, and the agent sources /var/lib/formant/.bashrc from there exactly as a native install does. Edit the file on the host, then restart the container:

   Shell

   echo 'export FORMANT_UPLOAD_RATE_LIMIT_KBPS=750' | sudo tee -a /var/lib/formant/.bashrc
   docker restart formant-agent

   A value in .bashrc overrides the same variable passed with -e, because the file is sourced after the container environment is applied.

📘

If the default value for an environment variable is empty, this variable has no effect until you set a value.

❗️

Restart the agent for changes to take effect

• Native: sudo systemctl restart formant-agent
• Docker: docker restart formant-agent (or re-run the installer if you changed -e arguments)

For more information, see Installing the Formant agent: Starting and stopping the agent and Install the Formant agent via Docker: Managing a Docker installation.

ROS environment variables

General environment variables

Upload pacing environment variables

Available from agent 1.372.0.

By default the agent uploads recorded assets as fast as the link allows, several files in parallel. On a shared or metered uplink, for example several robots behind one satellite or cellular link, a backlog draining after a connectivity gap can take the whole uplink and degrade a live teleoperation session. These two variables put a ceiling on that traffic.

What is and is not paced

• Numeric, text, bitset, location and small JSON datapoints are not paced. They travel on the low-latency ingest path so that dashboards and teleop telemetry stay live.
• During a teleop session the agent also stops draining its on-disk backlog of datapoints and logs until the session ends. Live values keep flowing; only buffered history waits.
• On-demand uploads share the asset path and are paced and held the same way.

Sizing the cap

The cap is per agent, not per network link. To protect a shared uplink:

1. Divide the uplink capacity by the number of robots on the link.
2. Subtract headroom for the teleop video you want to keep smooth.
3. Set the result on every robot on the link. One robot without a cap can fill the link by itself.

Example: four robots on a 5 Mbps uplink. 5000 ÷ 4 = 1250 kbps would still fill the link, so 750 kbps per robot leaves about 2 Mbps for teleop. In Formant's test of this exact setup, a 3000 kbps cap on each robot changed nothing (4 × 3000 = 12 Mbps of demand never binds), while 750 kbps held the link at about 64% with a worst-case round trip of 35 ms.

A capped backlog drains more slowly: a large multi-part upload takes roughly three times longer under a cap, because paced uploads send one part at a time. Choose a cap that lets the backlog clear between sessions, and use a teleop cap of 0 (hold) or a small value if teleop quality matters more than upload latency.

Verifying the cap

The agent logs the caps it applied once at startup:

pacing uploads at 750 kbps; asset uploads are held during teleop (FORMANT_TELEOP_UPLOAD_RATE_LIMIT_KBPS unset)
pacing uploads at 750 kbps, and 250 kbps while teleop is active
upload pacing is off (FORMANT_UPLOAD_RATE_LIMIT_KBPS unset)

Native: journalctl -u formant-agent | grep "pacing uploads". Docker: docker logs formant-agent 2>&1 | grep "pacing uploads". If you see upload pacing is off after setting the variable, the agent did not see it: check the file or -e argument, then restart the agent (see Where to set environment variables).

Media environment variables

See also

• Install the Formant agent
• Install the Formant agent via Docker
• Ingesting telemetry data
  • Add a video stream
• Teleoperation
  • Add a teleoperation image stream