Miru Agent

The Miru Agent is a Rust binary that runs on devices (robots), manages configuration deployments, reports device state, and communicates with the Miru backend over HTTP and MQTT.

For detailed documentation and usage instructions, please visit the official documentation.

Repository structure

agent/
├── agent/                  # Main binary (miru-agent)
│   ├── src/                #   Application source
│   ├── tests/              #   Integration tests (mirrors src/ structure)
│   └── build.rs            #   Build script (embeds git hash, validates version)
├── api/                    # OpenAPI specs and codegen config
├── build/                  # Docker, GoReleaser, release scripts
├── libs/                   # Generated libraries (do not edit)
│   ├── backend-api/        #   Backend API client
│   └── device-api/         #   Device API server
├── scripts/                # Dev tooling (test, lint, coverage, etc.)
└── testdata/               # Test fixtures

See ARCHITECTURE.md for a deeper explanation of how things fit together.

Prerequisites

• Rust stable (see rust-version in Cargo.toml for current MSRV)
• Optional for linting: cargo-machete, cargo-diet, cargo-audit
• Optional for coverage: cargo-llvm-cov, jq

Building

cargo build -p miru-agent            # debug
cargo build -p miru-agent --release  # release

Testing

cargo test
cargo test --package miru-agent
./scripts/test.sh

Ordinary Cargo tests require no custom features or logging environment. The wrapper runs RUST_LOG=off cargo test --package miru-agent to suppress log output.

The main suite in agent/tests/mod.rs is an external integration target that exercises the ordinary library's public APIs; cases needing private access live in inline #[cfg(test)] modules under agent/src/. See AGENTS.md § Testing for target layout, fixture rules, and #[serial] conventions.

Coverage gates

./scripts/covgate.sh

Each module has a .covgate file setting its minimum coverage threshold. The script runs tests with cargo-llvm-cov and checks each module's coverage against its gate.

Linting

./scripts/lint.sh

Runs: cargo update (updates Cargo.lock), the custom import linter, cargo fmt, unused dependency checks (machete, diet), security audit, and clippy with -D warnings.

CI/CD

The CI workflow (ci.yml) runs on every push and pull request. See the workflow file for the current job list.

The Builder workflow (builder.yml) builds and pushes the builder Docker image to GHCR when build/Dockerfile.builder changes.

The Release workflow (release.yml) triggers on git tags, runs CI, then builds via GoReleaser.

Releasing

Releases are tag-triggered. GoReleaser cross-compiles for x86_64 and aarch64 Linux and produces .deb packages. The build script (agent/build.rs) validates that the git tag matches the version in Cargo.toml.

Further reading

• ARCHITECTURE.md — System design, codemap, invariants
• AGENTS.md — Conventions for AI coding agents
• Official documentation — User-facing docs