Flatcar Linux

This guide walks you through installing the Infrastructure Agent (Infra Agent) on a Flatcar Linux machine. These instructions can also be found on the Installation page in the Middleware application.

Prerequisites#

Butane to translate human-readable Butane configs into Ignition for Flatcar Linux.
Ignition as the provisioning format used by Flatcar Container Linux.
A running Flatcar Linux node with Docker installed.

1 Butane Configuration#

Add the mw-agent.service systemd unit to your Butane config:

1variant: flatcar
2version: 1.0.0
3systemd:
4  units:
5    - name: mw-agent.service
6      enabled: true
7      contents: |
8        [Unit]
9        Description=Middleware Agent
10        After=docker.service
11
12        [Service]
13        Environment="MW_API_KEY=<MW_API_KEY>"
14        Environment="MW_TARGET=https://<MW_UID>.middleware.io:443"
15        ExecStart=/usr/bin/docker run \
16          --name mw-agent \
17          --privileged \
18          -e MW_API_KEY \
19          -e MW_TARGET \
20          ghcr.io/middleware-labs/mw-host-agent:master
21        Restart=always
22
23        [Install]
24        WantedBy=multi-user.target

Replace <MW_API_KEY> and <MW_UID> with your actual values.

2 Ignition Configuration#

Convert your Butane file into an Ignition manifest:

1butane your-configuration.bn > ignition.ign

Use the resulting ignition.ign when provisioning your Flatcar node.

3 Add Host Tags [Optional]#

Embed custom tags by setting MW_HOST_TAGS (comma-separated key:value) alongside your API key:

1MW_HOST_TAGS=env:production,role:web MW_API_KEY="<MW_API_KEY>"

Verify tags under Infrastructure → [Your Host] → System Information in the Middleware UI.

Managing the Agent Service#

Control the mw-agent.service via systemd:

Action	Command
Start Agent	`sudo systemctl start mw-agent.service`
Stop Agent	`sudo systemctl stop mw-agent.service`
Restart Agent	`sudo systemctl restart mw-agent.service`
Check service status	`sudo systemctl status mw-agent.service`
View service logs	`sudo journalctl -u mw-agent.service --no-pager`
Verify Docker container	`docker ps -a --filter ancestor=ghcr.io/middleware-labs/mw-host-agent:master`

4 Verify Installation#

Confirm the Infra Agent container is present and check its exit code:

1docker ps -a --filter ancestor=ghcr.io/middleware-labs/mw-host-agent:master

UP or a clean exit → installation succeeded
No container or error state → installation failed

5 Check Your Dashboard#

Navigate to Middleware → Unified Dashboard. Allow a few minutes for metrics to appear. If data is missing, proceed to Troubleshooting.

Troubleshooting#

If metrics don’t appear after a few minutes, check for the following:

Service health:

1sudo systemctl status mw-agent.service

Agent logs:

1sudo journalctl -u mw-agent.service --no-pager
2docker logs mw-agent

Config verification: Ensure your MW_API_KEY and MW_TARGET are correctly set in the Ignition config.
Network: Confirm your node can reach https://<MW_UID>.middleware.io:443.
Further help: Get in touch with us via our Contact Us.

Uninstall#

If you need to remove the Middleware.io Infra Agent from your Fedora CoreOS host, follow these steps:

1 Stop & disable the service:#

1sudo systemctl stop mw-agent.service
2sudo systemctl disable mw-agent.service

2 Remove the systemd unit:#

1sudo rm /etc/systemd/system/mw-agent.service
2sudo systemctl daemon-reload

3 Remove the Docker container:#

1docker rm -f mw-agent

4 (Optional) Remove the agent image:#

1docker rmi ghcr.io/middleware-labs/mw-host-agent:master

5 Clean up Ignition/Butane configs:#

Remove the mw-agent.service snippet from your .bn/.ign files before reprovisioning.

Need assistance or want to learn more about Middleware? Get in touch with us via our Contact Us or join our Slack channel.