---
title: "CoreOS"
description: "Integrate Middleware Monitoring Agent with CoreOS using Butane & Ignition for automated system monitoring and operational insight."
section: "Agent Installation"
breadcrumb: "Linux > CoreOS"
canonical: "https://docs.middleware.io/get-started/agent/linux/coreos"
---
# CoreOS

The Middleware Infrastructure Agent collects telemetry from Fedora CoreOS nodes. Its container-based deployment is managed by systemd through Butane configuration, keeping monitoring setup in the host provisioning workflow.

The Agent runs as a container managed by a systemd service defined through your Fedora CoreOS Butane configuration.

## Prerequisites

Before installing the Infrastructure Agent on Fedora CoreOS, make sure you have:

- **Butane** — Required to convert human-readable Butane configuration files into machine-readable Ignition configurations.
- **A running Fedora CoreOS node** — The node must have Docker available to run the Middleware Infrastructure Agent.

## Installation

#### 1 Create the Butane configuration

Add the `mw-agent.service` systemd unit to your existing Butane configuration.

The service starts and manages the Middleware Infrastructure Agent container on the Fedora CoreOS node.

```yml
    variant: fcos
version: 1.5.0
systemd:
 units:
   - name: mw-agent.service
     enabled: true
     contents: |
       [Unit]
       Description=Middleware Agent
       After=docker.service
       [Service]
       Environment="MW_API_KEY=your-initial-token"
       Environment="MW_TARGET=your-initial-uid"
       ExecStart=/usr/bin/docker run \
         --name mw-agent \
         --privileged \
         -e MW_API_KEY \
         -e MW_TARGET \
         ghcr.io/middleware-labs/mw-host-agent:master
       Restart=always
       [Install]
       WantedBy=multi-user.target
```

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

#### 2 Generate the Ignition configuration

Convert the Butane configuration into an Ignition configuration.

```bash
    butane your-configuration.bn > ignition.ign
```

This generates the `ignition.ign` file.

Use the contents of `ignition.ign` when provisioning your Fedora CoreOS node. The configuration creates the required `systemd` service and starts the Middleware Infrastructure Agent during node initialization.

#### 3 Add host tags (optional)

To associate custom tags with the host, set the MW_HOST_TAGS environment variable in the Agent configuration along with your Middleware API key.
Specify multiple tags as comma-separated key=value pairs.

```bash
    MW_HOST_TAGS=key1:value1,key2:value2,... MW_API_KEY="your-initial-token"
```

After the host starts reporting data, verify the configured tags in the Middleware UI:

**Infrastructure → [Your Host] → System Information**

#### 4 Verify the installation

After provisioning the Fedora CoreOS node, verify that the Middleware Agent container was created and check its status.

Run:

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

Check the command output:

- **Up** — The Agent container is running and the installation was successful.
- **Exited** — The Agent container was created but is no longer running. Check the container logs and exit code to determine whether additional troubleshooting is required.
- **Blank output** — The Agent container was not created. Review the Butane/Ignition configuration and provisioning process.

## Manage the agent (Commands)

Middleware agent runs as a systemd service in Linux based systems, usually on Linux systems, the Middleware Agent runs as a systemd service. The service definition is typically located under:

```bash
/usr/lib/systemd/system/
```

Use the following commands to start, stop, restart, and check the status of the Middleware Agent.

| 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` |

## Verify data collection

After installing the Agent, allow a few moments for the host to start reporting telemetry.

Go to [**Infrastructure Monitoring → Hosts**](https://app.middleware.io/infrastructure/host) and verify that your Linux host appears and is reporting metrics.

After data collection starts, you can:

- View host metrics in [Infrastructure Monitoring](https://app.middleware.io/infrastructure/).
- View collected host logs in [Log Monitoring](https://app.middleware.io/logs).
- Create [alerts](/features/alerts) for collected metrics.
- Create [custom dashboards](/features/dashboards) to visualize Linux host metrics.

## Uninstall

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

#### 1 Stop & disable the service:

```bash
    sudo systemctl stop mw-agent.service
sudo systemctl disable mw-agent.service
```

#### 2 Remove the systemd unit:

```bash
    sudo rm /etc/systemd/system/mw-agent.service
sudo systemctl daemon-reload
```

#### 3 Remove the Docker container:

```bash
    docker rm -f mw-agent
```

#### 4 (Optional) Remove the agent image:

```bash
    docker 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.

## Troubleshooting

**Data is not coming after agent installation ?**

It may take a few moments for telemetry to appear after a new Agent installation.
First, go to [Infrastructure Monitoring → Hosts](https://app.middleware.io/infrastructure/host) and check whether the host is reporting data.

If the host does not appear or data is not being collected, check the following:

**Check network connectivity.**
Verify that the host can establish an outbound HTTPS connection to:
`https://<YOUR_UID>.middleware.io:443`

**Check for multiple Agents.**
Make sure only one Middleware Infrastructure Agent is running on the host.

**Check Agent logs.**
Review the Agent log file for errors:
`/var/log/mw-agent/mw-agent.log`
You can also inspect the service logs using `journalctl`.

**Check proxy configuration.**
If the host is behind a corporate proxy, verify that the required `HTTP_PROXY` and `HTTPS_PROXY` environment variables are configured correctly and that the proxy allows connections to Middleware.

**Check permissions.**
Make sure the installation and Agent management commands are run with sufficient privileges. Use `sudo` where required.

If you’re still unsure about the issue , you may reach out to Middleware support team via chatbot (which you are seeing at right bottom corner of this page) or email at support@middleware.io.

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