--- updatedAt: 2026-09-24T14:52:59.000Z agentTools: projectIndex: https://docs.formant.io/llms.txt --- # Install the Formant agent via Docker (ROS1) Install the Formant agent on a ROS1 device with Docker, including provisioning, updates, image tags, and extra Docker arguments. Install the Formant agent on a ROS1 device by running the Docker-based installer. # Prerequisites ### System requirements The Formant agent is an extremely lightweight tool which sets up data pipelines on your device. The base footprint of the agent itself on a device is minimal. Depending on your application, you can configure the agent and your device to store and transfer large amounts of data (e.g., video cache and streaming), which will require greater memory and CPU capability. | Supported Operating Systems | Support ROS Version | Supported Architectures | | :-------------------------- | :------------------ | :---------------------- | | Ubuntu 20.04 ("*Focal*") | ROS1 ("*Noetic*") | `amd64` `arm64` | | Ubuntu 18.04 ("*Bionic*") | ROS1 ("*Melodic*") | `amd64` `arm64` | ### Install Docker to your device Install Docker on the target device before you install the Formant agent. ### Create a device Follow the instructions in [Create a device](https://docs.formant.io/docs/getting-started-create-a-device) to add a new device to your Formant organization. ### Internet connectivity The target device must have connectivity to `app.formant.io` and `api.formant.io`. You can run the following script on your device terminal to output the robot's details and verify prerequisites: ```shell bash <(wget -qO - https://app.formant.io/device-check.sh) ``` ### Terminal access To install the Formant agent on the target device, you must have terminal access to the device and the ability to run commands. *** # Step 1: Install the Formant agent Follow the instructions in [Create a device](https://docs.formant.io/docs/getting-started-create-a-device) to generate a provisioning token for the target device. The provisioning token is unique to the device and expires after 72 hours. Run the installer with Docker and ROS1 enabled: ```shell bash <(wget -qO - https://app.formant.io/install-agent.sh) --method docker --ros 1 ``` To ingest custom ROS message types, pass your catkin workspace path with `--ros-workspace`: ```shell bash <(wget -qO - https://app.formant.io/install-agent.sh) --method docker --ros 1 --ros-workspace /home/ubuntu/catkin_ws ``` > 📘 Ensure the ROS master is running > > The Formant agent needs to communicate with the ROS master running on your device in order to properly ingest ROS data. > > You can check that the ROS master is running by using a command like `rostopic list`. # Step 2: Verify successful installation If the Formant agent has been installed and connection established, Formant will begin ingesting telemetry for default streams like CPU, Network, Memory, and Disk. 1. In Formant, in the upper-left corner, open the menu. Under the **Observe** tab, click on the name of your device. 2. Verify that these streams have live telemetry data in the device's telemetry page. {1192}

Telemetry data uploaded to a default stream. *** # Managing a Docker installation > 🚧 > > Docker installations of the Formant agent do not support automatic, over-the-air (OTA) agent updates. > > To update the Formant agent, you will have to update the `formant-agent` Docker image on your device. > > Pull a version-specific or `latest--` tag (for example `latest-melodic-amd64`). The bare `latest` tag is not kept current. ### Updating or re-running after provisioning To update the agent or re-run the installer after provisioning, omit the provisioning token. The script detects existing credentials at `/var/lib/formant/credentials.toml` and skips provisioning. ```shell bash <(wget -qO - https://app.formant.io/install-agent.sh) --method docker --ros 1 ``` ### Browsing available image tags List available image tags when you need to pin a specific agent version or find the right image for your ROS distribution and architecture. ```shell # List all available tags bash <(wget -qO - https://app.formant.io/install-agent.sh) --show-tags all # Filter by keyword bash <(wget -qO - https://app.formant.io/install-agent.sh) --show-tags melodic ``` ### Install a specific agent image tag To pin the installation to a specific image tag, pass `--tag`: ```shell bash <(wget -qO - https://app.formant.io/install-agent.sh) --method docker --ros 1 --tag 1.228.1-ros-melodic-arm64 ``` ### Passing extra Docker arguments Pass [optional arguments to the Docker run command](https://docs.docker.com/engine/reference/run/) with `--extra-args`. For example, mount an additional volume and set a custom environment variable: ```shell bash <(wget -qO - https://app.formant.io/install-agent.sh) --method docker --ros 1 \ --extra-args "-v /data/robot:/data/robot -e MY_VAR=value" \ ``` ### Setting environment variables The agent's behavior is controlled by [environment variables](https://docs.formant.io/docs/environment-variables-for-the-agent). On a Docker installation you can set them in two ways: * Pass `-e NAME=value` through `--extra-args` (as above). The container environment is fixed when the container is created; to change it, re-run the installer without the provisioning token and with the new `--extra-args`. * Add `export NAME=value` lines to `/var/lib/formant/.bashrc` on the host. The installer mounts this directory into the container and the agent sources the file at startup, exactly as a native installation does. Values here override `-e` values. Either way, the agent only reads its environment when it starts. Run `docker restart formant-agent` after editing `.bashrc`. ### Enabling and disabling the agent running on startup By default, after installation, the agent runs on startup. To set the agent to run on startup: ```shell docker update --restart=yes formant-agent ``` To disable the agent from running on startup: ```shell docker update --restart=no formant-agent ``` ### Starting and stopping the agent By default, the agent will be enabled and run on startup. To start the agent: ```shell docker start formant-agent ``` To stop the agent: ```shell docker stop formant-agent ``` To restart the agent: ```shell docker restart formant-agent ``` ### Retrieving agent logs ```shell docker logs -f formant-agent ``` ### Uninstalling the Formant agent This command stops any running `formant-agent` containers and removes the `formant-agent` image: ```shell docker rm -f formant-agent ``` To remove the agent credentials as well, run: ```shell rm -rf /var/lib/formant ``` # See also * [Install the Formant agent](https://docs.formant.io/docs/getting-started-install-the-formant-agent) * [Environment variables for the agent](https://docs.formant.io/docs/environment-variables-for-the-agent) * [Troubleshooting an agent installation](https://docs.formant.io/docs/troubleshooting-an-agent-installation) * [Error invoking Docker in Formant terminal](https://docs.formant.io/docs/troubleshooting-error-docker-formant-terminal) ### If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at [support@formant.io](mailto:support@formant.io).