# Racksmith

**Agentic bare-metal lab operations** — inventory, commissioning, deploy, fabric audit, and job scheduling — with first-class [Hermes Agent](https://hermes-agent.nousresearch.com/) skills and an MCP tool server.

> **Live demo:** [amiirhosseini.github.io/racksmith](https://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](https://amiirhosseini.github.io/racksmith/), [walkthrough](docs/DEMO.md), and source. Optional local CLI/API for your laptop only.

[![Live Demo](https://img.shields.io/badge/demo-live-4f9fd9)](https://amiirhosseini.github.io/racksmith/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-green.svg)](pyproject.toml)
[![GitHub](https://img.shields.io/badge/github-Amiirhosseini%2Fracksmith-181717)](https://github.com/Amiirhosseini/racksmith)

## 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)

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

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

```bash
pip install -e .
racksmith install-hermes-skills
```

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

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

### 3. Run the MCP server

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

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

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

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

## CLI cheat sheet

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

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

```bash
docker compose up --build
```

## Project layout

```text
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](CONTRIBUTING.md). Bug reports and lab war-stories welcome.

## License

Apache License 2.0 — see [LICENSE](LICENSE).

## Acknowledgments

- [Canonical MAAS](https://maas.io/) — metal-as-a-service inspiration and API shapes
- [Nous Research Hermes Agent](https://hermes-agent.nousresearch.com/) — self-improving agent runtime + skills
- [agentskills.io](https://agentskills.io) — portable skill format