Racksmith

Agentic bare-metal lab operations — inventory, commissioning, deploy, fabric audit, and job scheduling — with first-class Hermes Agent skills and an MCP tool server.

Live demo: amiirhosseini.github.io/racksmith
Interactive lab health + agent plan preview (GitHub Pages, no server).

Racksmith helps operators run MAAS-style hardware labs without drowning in failed commissions, silent BMC outages, VLAN drift, and empty Ready pools. It ships a simulation backend so you can try the full workflow with zero hardware.

No cloud server required. Browse the live demo, walkthrough, and source. Optional local CLI/API for your laptop only.

Why it exists

Bare-metal labs fail in boring, expensive ways:

• Commissioning hangs or fails and nobody notices until a job queue stalls
• TOR VLANs drift from inventory intent
• Deployed hosts never get released → Ready capacity hits zero
• Operators re-learn the same remediation path every week

Racksmith turns those paths into inspectable plans, guardrailed actions, and Hermes skills that improve as you use them.

Features

Area	What you get
MAAS client	Async REST client for commission / allocate / deploy / release / power
Sim lab	Deterministic 12-node Toronto-style lab for demos & CI
Health engine	Findings for BMC, thermal, commissioning, capacity, switch fabric
Agent planner	Natural-language goals → ranked action plans
MCP server	Tools for Hermes / Claude / any MCP client
Hermes skills	lab-health, lab-commission, switch-audit, fleet-deploy
Job queue	Testflinger-style enqueue → allocate → deploy worker
HTTP API	FastAPI for dashboards and automation

Quick start (simulation)

git clone https://github.com/Amiirhosseini/racksmith.git
cd racksmith
python -m venv .venv

# Linux / macOS
source .venv/bin/activate
# Windows PowerShell
# .\.venv\Scripts\Activate.ps1

pip install -e ".[dev]"
cp config/racksmith.example.yaml config/racksmith.yaml

racksmith health
racksmith machines
racksmith plan "fix failed commissioning and show capacity"
racksmith run "commission failed machines" --execute

Start the API:

racksmith serve
# http://127.0.0.1:8787/docs

Hermes Agent integration

1. Install Hermes

Follow the official installer: https://hermes-agent.nousresearch.com/docs/getting-started/installation

2. Install Racksmith skills

pip install -e .
racksmith install-hermes-skills

Or point Hermes at this repo’s skill tree in ~/.hermes/config.yaml:

skills:
  external_dirs:
    - /absolute/path/to/racksmith/hermes/skills

3. Run the MCP server

racksmith mcp

Example Hermes chat prompts:

• /lab-health — morning lab audit
• /lab-commission recover failed hosts
• /fleet-deploy allocate Ubuntu noble on amd-epyc
• /switch-audit check TOR VLAN drift

Talk to a real MAAS

# config/racksmith.yaml
backend: maas
maas:
  url: http://maas.example:5240/MAAS
  api_key: consumer_key:token_key:token_secret
  verify_tls: true

pip install -e ".[oauth,dev]"
export RACKSMITH_BACKEND=maas
export RACKSMITH_MAAS_URL=http://maas.example:5240/MAAS
export RACKSMITH_MAAS_API_KEY='consumer:token:secret'
racksmith health

Architecture

┌──────────────────┐     ┌─────────────────┐     ┌──────────────────┐
│  Hermes / MCP    │────▶│  Racksmith API  │────▶│  MAAS or SimLab  │
│  CLI / skills     │     │  planner/tools  │     │  machines+power  │
└──────────────────┘     └────────┬────────┘     └──────────────────┘
                                  │
                                  ▼
                         ┌─────────────────┐
                         │ Health + Fabric │
                         │ Job scheduler   │
                         └─────────────────┘

CLI cheat sheet

racksmith health
racksmith machines --status Ready
racksmith plan "deploy ubuntu noble on 100g"
racksmith run "deploy ubuntu noble on 100g" --execute --yes
racksmith commission <system_id> --ssh
racksmith job kernel-smoke --tags intel-xeon --run
racksmith serve --host 0.0.0.0 --port 8787
racksmith mcp

HTTP API

Method	Path	Purpose
GET	/healthz	Liveness
GET	/v1/snapshot	Full lab snapshot + findings
GET	/v1/machines	Machine inventory
POST	/v1/plan	{ "goal": "..." } → agent plan
POST	/v1/actions	Execute a tool action
POST	/v1/jobs	Enqueue lab job
POST	/v1/jobs/run-next	Worker tick

Safety model

Default agent.mode is assist:

• Plans are always allowed
• Mutating actions (deploy, power_cycle, release, mark_broken) need --yes / confirm=true

Set agent.mode: autopilot only on dedicated labs with clear ownership.

Development

pip install -e ".[dev,oauth]"
pytest -q
ruff check src tests

docker compose up --build

Project layout

racksmith/
├── src/racksmith/          # Python package
│   ├── maas/               # MAAS client + simulator
│   ├── monitoring/         # Health findings
│   ├── network/            # Switch intent audit
│   ├── scheduler/          # Job queue
│   ├── agent/              # Planner + MCP server
│   ├── api/                # FastAPI app
│   └── cli.py
├── hermes/skills/          # Hermes / agentskills.io skills
├── config/                 # Example + default YAML
├── tests/
└── docs/

Roadmap

• [ ] Live NETCONF / SONiC config apply (gated)
• [ ] Prometheus metrics exporter
• [ ] Testflinger webhook receiver
• [ ] Multi-lab federation
• [ ] Redfish-native inventory enrichment

Contributing

See CONTRIBUTING.md. Bug reports and lab war-stories welcome.

License

Apache License 2.0 — see LICENSE.

Acknowledgments

• Canonical MAAS — metal-as-a-service inspiration and API shapes
• Nous Research Hermes Agent — self-improving agent runtime + skills
• agentskills.io — portable skill format